Skip to content

ref(develop/sdks): Clarify Exception Mechanism interface #14957

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 19, 2025
Merged

ref(develop/sdks): Clarify Exception Mechanism interface #14957

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
16a785f
ref(sdks): Clarify Event Mechanism interface
Lms24 Sep 17, 2025
0f64a95
Apply suggestions from code review
Lms24 Sep 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 120 additions & 53 deletions develop-docs/sdk/data-model/event-payloads/exception.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,89 +51,156 @@ created this exception.
`stacktrace`

: An optional stack trace object corresponding to the [Stack Trace Interface](/sdk/data-model/event-payloads/stacktrace/).

## Exception Mechanism

The exception mechanism is an optional field residing in the _Exception
Interface_. It carries additional information about the way the exception was
created on the target system. This includes general exception values obtained
from the operating system or runtime APIs, as well as mechanism-specific values.
The exception mechanism is an optional field residing in the _Exception Interface_.
It carries additional information about the way the exception was created and captured ("capturing mechanism") on the target system.
This includes general exception values obtained from the operating system or runtime APIs, as well as capturing mechanism-specific values.

### Attributes

`type`
#### `type`

Required (`string`)

The identifier of the capturing mechanism that captured the exception.
The chosen mechanism `type` MUST help users as well as Sentry employees determine the responsible mechanism for capturing the exception.
This is either instrumentation within our SDKs or users manually capturing exceptions (for example via `captureException`).

The `type` MUST be _reasonably unique_ to make it possible to identify the integration or SDK API that performed the capture.
There's no strict uniqueness requirement as in certain situations, multiple paths exist within one instrumentation, in which case it is fine to use a common mechanism `type`.

For user-invoked exception captures (e.g. via `captureException`), the `type` MUST be set to `'generic'`.

For SDK-invoked exception captures, the mechanism `type` value MUST NOT be set to `'generic'` and SHOULD follow the [Trace Origin](/sdk/performance/trace-origin/) naming scheme whenever applicable.
For example, if a span is wrapping the exception capture logic, `type` should be equal to this span's `sentry.origin` attribute.
If no (specific) span is present, the `type` SHOULD be set to an adequate value, following the Trace Origin naming scheme as closely as possible.

<Expandable title="Examples">

: Required unique identifier of this mechanism determining rendering and processing of the mechanism data.
Exception capture within a span:

`description`
```js
startSpan(
{
name: 'Middleware',
attributes: { 'sentry.origin': 'auto.http.express.middleware' },
},
() => {
captureException(error, {
mechanism: { type: 'auto.http.express.middleware', handled: false }
});
},
);
```

Exception capture outside of a span:

```js
captureException(error, {
mechanism: { type: 'auto.browser.global_handlers.onerror', handled: false }
});
```

Use `'generic'` for user-invoked exception captures (i.e. default value):

```js
function captureException(error, context) {
const mechanism = {
type: 'generic',
handled: true,
...context?.mechanism,
}
// ...
}
```

: Optional human-readable description of the error mechanism and a possible hint on how to solve this error.

`help_link`
</Expandable>

: Optional fully qualified URL to an online help resource, possibly interpolated with error parameters.
<Expandable title="Why Trace Origin?">

`handled`
Historically, there was no requirement for the `type` attribute naming scheme.
Consequently, different SDKs took diffferent approaches as to how they set the `type` attribute.
In some cases, the `type` attribute was/is not set at all.
Chosing [Trace Origin](/sdk/performance/trace-origin/) as the naming scheme for the `type` attribute means that we're using an already established and accepted naming scheme.
The scheme works well enough for the exception mechanism `type` attribute.
Slight deviations to accomodate for the applicability to exceptions are allowed and to be expected.
SDK maintainers are free to migrate to the new naming scheme for existing capturing mechanisms or use it when adding new mechanisms.

: Optional flag indicating whether the user has handled the exception (for example, via `try ... catch`).
</Expandable>

`synthetic`
#### `handled`

: An optional flag indicating that this error is synthetic. Synthetic errors are errors that
carry little meaning by themselves. This may be because they are created at a central
place (like a crash handler), and are all called the same: `Error`, `Segfault` etc.
When the flag is set, Sentry will then try to use other information (top in-app frame
function) rather than the exception type and value in the UI for the primary event display.
Furthermore, if this flag is set, Sentry will ignore the exception `type` when grouping the
exception into issues.
: This flag should be set for all "segfaults" for instance as every single error group would
look very similar otherwise. Also, errors the SDK creates to add a stack trace to events
that don't have one themselves should be marked as `synthetic` (This happens, for example,
when users set `attachStackTrace: true` and capture a string message via `captureException`
or `captureMessage`.)
Optional (`boolean`)

`exception_id`
Flag indicating whether the user has handled the exception (for example, via `try ... catch`).

: An optional numeric value providing an ID for the exception relative
to this specific event. The SDK should assign simple incrementing integers
to each exception in the tree, starting with 0 for the root of the tree.
In other words, when flattened into the list provided in the exception
values on the event, the last exception in the list should have ID 0,
the previous one should have ID 1, the next previous should have ID 2, etc.
#### `description`

`parent_id`
Optional (`string`)

: An optional numeric value pointing at the exception_id that is the
parent of this exception. The SDK should assign this to all exceptions except
the root exception (the last to be listed in the exception values).
Human-readable description of the error mechanism and a possible hint on how to solve this error.

`is_exception_group`
#### `help_link`

: An optional flag indicating that this exception is part of an exception group type specific to the platform or language.
Optional (`string`)

`source`
Fully qualified URL to an online help resource, possibly interpolated with error parameters.

: An optional string value describing the source of the exception. The SDK should populate this with the name of the property or attribute of the parent exception that this exception was acquired from. In the case of an array, it should include the zero-based array index as well.
#### `synthetic`

Optional (`boolean`)

Flag indicating that this error is synthetic.
Synthetic errors are errors that carry little meaning by themselves.
This may be because they are all created at a central place (like a crash handler), and share the same title: `Error`, `Segfault` etc.
When the flag is set, Sentry will then try to use other information (top in-app frame function) rather than the exception type and value in the UI for the primary event display.
Furthermore, if this flag is set, Sentry will ignore the exception `type` when grouping the exception into issues.
This flag SHOULD be set for all "segfaults" for instance as every single error group would look very similar otherwise.
Also, errors the SDK creates to add a stack trace to events that don't have one themselves SHOULD be marked as `synthetic` (This happens, for example, when users set `attachStackTrace: true` and capture a string message via `captureException` or `captureMessage`.)

#### `exception_id`

Optional (`number`)

An optional numeric value providing an ID for the exception relative to this specific event.
The SDK SHOULD assign simple incrementing integers to each exception in the tree, starting with 0 for the root of the tree.
In other words, when flattened into the list provided in the exception values on the event, the last exception in the list SHOULD have ID 0,
the previous one SHOULD have ID 1, the next previous SHOULD have ID 2, etc.

#### `parent_id`

Optional (`number`)

An optional numeric value pointing at the exception_id that is the parent of this exception.
The SDK SHOULD assign this to all exceptions except the root exception (the last to be listed in the exception values).

#### `is_exception_group`

Optional (`boolean`)

Flag indicating that this exception is part of an exception group type specific to the platform or language.

#### `source`

Optional (`string`)

An optional string value describing the source of the exception.
The SDK SHOULD populate this with the name of the property or attribute of the parent exception that this exception was acquired from.
In the case of an array, it SHOULD include the zero-based array index as well.

- Python Examples: `"__context__"`, `"__cause__"`, `"exceptions[0]"`, `"exceptions[1]"`
- .NET Examples: `"InnerException"`, `"InnerExceptions[0]"`, `"InnerExceptions[1]"`
- JavaScript Examples: `"cause"`, `"errors[0]"`, `"errors[1]"`

`meta`

: Optional information from the operating system or runtime on the exception
mechanism (see [meta information](#meta-information)).
#### `meta`

`data`
Optional information from the operating system or runtime on the exception mechanism (see [meta information](#meta-information)).

: Arbitrary extra data that might help the user understand the error thrown by
this mechanism.
#### `data`

<Alert title="Note" level="warning">
The <code>type</code> attribute is required to send any exception mechanism attribute, even
if the SDK cannot determine the specific mechanism. In this case, set the <code>type</code>
to <code>generic</code>. See below for an example.
</Alert>
Arbitrary extra data that might help the user understand the error thrown by this mechanism.

### Meta information

Expand Down
Loading