Concepts - Docs | Transactional

Data Model Overview

Error tracking uses a hierarchical data model:

Project
└── Issues (grouped errors)
    └── Occurrences (individual error events)

Issues vs Occurrences

Understanding the difference between issues and occurrences is fundamental to error tracking.

Issues

An issue represents a unique error type. Multiple error events that have the same root cause are grouped into a single issue.

// Issue: TypeError - Cannot read property 'name' of undefined
{
  id: "issue-abc123",
  fingerprint: "sha256:a1b2c3...",
  title: "TypeError: Cannot read property 'name' of undefined",
  culprit: "src/components/UserCard.tsx:42",
  status: "UNRESOLVED",
  severity: "ERROR",
  platform: "REACT",
  occurrenceCount: 156,
  userCount: 23,
  firstSeen: "2024-01-15T10:00:00Z",
  lastSeen: "2024-01-15T14:30:00Z",
}

Occurrences

An occurrence is a single error event - one specific instance when an error happened.

// Occurrence: One specific error event
{
  id: "occ-xyz789",
  issueId: "issue-abc123",
  eventId: "evt-123456",
  timestamp: "2024-01-15T14:30:00Z",
  severity: "ERROR",
  exceptionType: "TypeError",
  exceptionValue: "Cannot read property 'name' of undefined",
  stackTrace: { frames: [...] },
  userId: "user-456",
  userEmail: "john@example.com",
  environment: "production",
  release: "1.2.3",
  url: "https://app.example.com/users/123",
  breadcrumbs: [...],
  tags: { feature: "user-profile" },
}

Relationship

1 Issue = Many Occurrences

Issue: "TypeError: Cannot read property 'name' of undefined"
├── Occurrence 1: User A, Chrome, 10:30 AM
├── Occurrence 2: User B, Safari, 10:31 AM
├── Occurrence 3: User C, Firefox, 10:45 AM
└── ... 153 more

Fingerprinting

Fingerprinting is how the system groups similar errors into issues. A fingerprint is a hash generated from:

Exception Type - The error class (TypeError, ReferenceError, etc.)
Stack Trace - The call stack frames (file, function, line)
Exception Message - The error message (with variables normalized)

How Fingerprinting Works

// These two errors have the SAME fingerprint (same issue):
 
// Error 1
throw new TypeError("Cannot read property 'name' of undefined");
// at UserCard (src/components/UserCard.tsx:42:15)
// at renderUser (src/pages/Profile.tsx:88:20)
 
// Error 2
throw new TypeError("Cannot read property 'name' of undefined");
// at UserCard (src/components/UserCard.tsx:42:15)
// at renderUser (src/pages/Profile.tsx:88:20)

// These two errors have DIFFERENT fingerprints (different issues):
 
// Error 1 - Different stack trace
throw new TypeError("Cannot read property 'name' of undefined");
// at UserCard (src/components/UserCard.tsx:42:15)
 
// Error 2 - Different stack trace
throw new TypeError("Cannot read property 'name' of undefined");
// at UserList (src/components/UserList.tsx:67:10)

Custom Fingerprinting

You can override the default fingerprint:

obs.captureException(error, {
  fingerprint: ['checkout-payment-failed', error.code],
});

This groups errors by your custom logic instead of stack trace.

Severity Levels

Errors are classified by severity:

Level	Description	When to Use
`DEBUG`	Diagnostic information	Development debugging
`INFO`	Informational message	Notable events that aren't errors
`WARNING`	Potential issue	Degraded functionality, retries
`ERROR`	Error occurred	Caught exceptions, failed operations
`FATAL`	Critical failure	Unrecoverable errors, crashes

Setting Severity

// Manual capture with severity
obs.captureException(error, {
  severity: 'warning', // 'debug' | 'info' | 'warning' | 'error' | 'fatal'
});
 
// Capture a message with severity
obs.captureMessage('Payment retry succeeded after 3 attempts', 'warning');

Default Severity

Uncaught exceptions: error
Unhandled promise rejections: error
Manual captureException(): error
Manual captureMessage(): info

Issue Status

Issues have a lifecycle status:

Status	Description	Actions
`UNRESOLVED`	Active issue needing attention	Resolve, Ignore
`RESOLVED`	Fixed and deployed	Reopens on regression
`IGNORED`	Intentionally suppressed	Unignore

Status Transitions

New Error → UNRESOLVED
                ↓
      ┌─────────┴─────────┐
      ↓                   ↓
   RESOLVED            IGNORED
      ↓                   ↓
   (regression)      (unignore)
      ↓                   ↓
   UNRESOLVED        UNRESOLVED

Regression Detection

When a RESOLVED issue receives a new occurrence:

Issue status changes back to UNRESOLVED
REGRESSION alert triggers (if configured)
The issue appears at the top of the list

Platform Detection

The SDK automatically detects the platform:

Platform	Detection
`JAVASCRIPT`	Browser environment
`NODE`	Node.js runtime
`REACT`	React error boundaries
`NEXTJS`	Next.js instrumentation
`PYTHON`	Python SDK
`GO`	Go SDK
`OTHER`	Unknown/custom

Platform affects:

Stack trace formatting
Source map handling
Context enrichment

Data Retention

Error data is retained based on your plan:

Data Type	Free	Pro	Enterprise
Issues	30 days	90 days	1 year
Occurrences	7 days	30 days	90 days
Stack traces	7 days	30 days	90 days

Configure custom retention in project settings.

Next Steps

Capturing Errors - Learn how to capture errors
Stack Traces - Understand stack trace handling
Breadcrumbs - Track user actions
Context - Enrich errors with context