Skip to content

Commit 4a60a6d

Browse files
Lms24coolguyzone
Lms24
and
coolguyzone
authored
ref(develop/sdks): Clarify Exception Mechanism interface (#14957)
This PR clarifies the exception `Mechanism` interface, specifically the purpose and naming conventions for `mechanism.type`: - it now explicitly states that `type` should be used to indicate the "origin" or callsite of the exception, so that we can distinguish where an exception was captured. For instance, user vs. SDK but in case of the latter, type should be specific enough to know which instrumentation/integration within the SDK. - it suggests to use [Trace Origin](https://develop.sentry.dev/sdk/telemetry/traces/trace-origin/)-esque naming for SDK-captured events with the main motivation of this being an already established naming scheme that works well enough for this use case. To be clear, SDKs don't have to change anything right now, but should they want to ([like we did in JS](getsentry/sentry-javascript#17212)), this reworked doc should provide more clarity than the short descriptions previously. (I have another PR coming up with some refactors changes all over this doc but wanted to get this reviewed and accepted first since it actually changes content) closes getsentry/sentry-javascript#17266 closes getsentry/sentry-javascript#17212 (finally) --------- Co-authored-by: Alex Krawiec <[email protected]>
1 parent a46c312 commit 4a60a6d

File tree

1 file changed

+120
-53
lines changed

1 file changed

+120
-53
lines changed

‎develop-docs/sdk/data-model/event-payloads/exception.mdx‎

Lines changed: 120 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -51,89 +51,156 @@ created this exception.
5151
`stacktrace`
5252

5353
: An optional stack trace object corresponding to the [Stack Trace Interface](/sdk/data-model/event-payloads/stacktrace/).
54-
5554
## Exception Mechanism
5655

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

6260
### Attributes
6361

64-
`type`
62+
#### `type`
63+
64+
Required (`string`)
65+
66+
The identifier of the capturing mechanism that captured the exception.
67+
The chosen mechanism `type` MUST help users as well as Sentry employees determine the responsible mechanism for capturing the exception.
68+
This is either instrumentation within our SDKs or users manually capturing exceptions (for example via `captureException`).
69+
70+
The `type` MUST be _reasonably unique_ to make it possible to identify the integration or SDK API that performed the capture.
71+
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`.
72+
73+
For user-invoked exception captures (e.g. via `captureException`), the `type` MUST be set to `'generic'`.
74+
75+
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.
76+
For example, if a span is wrapping the exception capture logic, `type` should be equal to this span's `sentry.origin` attribute.
77+
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.
78+
79+
<Expandable title="Examples">
6580

66-
: Required unique identifier of this mechanism determining rendering and processing of the mechanism data.
81+
Exception capture within a span:
6782

68-
`description`
83+
```js
84+
startSpan(
85+
{
86+
name: 'Middleware',
87+
attributes: { 'sentry.origin': 'auto.http.express.middleware' },
88+
},
89+
() => {
90+
captureException(error, {
91+
mechanism: { type: 'auto.http.express.middleware', handled: false }
92+
});
93+
},
94+
);
95+
```
96+
97+
Exception capture outside of a span:
98+
99+
```js
100+
captureException(error, {
101+
mechanism: { type: 'auto.browser.global_handlers.onerror', handled: false }
102+
});
103+
```
104+
105+
Use `'generic'` for user-invoked exception captures (i.e. default value):
106+
107+
```js
108+
function captureException(error, context) {
109+
const mechanism = {
110+
type: 'generic',
111+
handled: true,
112+
...context?.mechanism,
113+
}
114+
// ...
115+
}
116+
```
69117
70-
: Optional human-readable description of the error mechanism and a possible hint on how to solve this error.
71118
72-
`help_link`
119+
</Expandable>
73120
74-
: Optional fully qualified URL to an online help resource, possibly interpolated with error parameters.
121+
<Expandable title="Why Trace Origin?">
75122
76-
`handled`
123+
Historically, there was no requirement for the `type` attribute naming scheme.
124+
Consequently, different SDKs took diffferent approaches as to how they set the `type` attribute.
125+
In some cases, the `type` attribute was/is not set at all.
126+
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.
127+
The scheme works well enough for the exception mechanism `type` attribute.
128+
Slight deviations to accomodate for the applicability to exceptions are allowed and to be expected.
129+
SDK maintainers are free to migrate to the new naming scheme for existing capturing mechanisms or use it when adding new mechanisms.
77130
78-
: Optional flag indicating whether the user has handled the exception (for example, via `try ... catch`).
131+
</Expandable>
79132
80-
`synthetic`
133+
#### `handled`
81134
82-
: An optional flag indicating that this error is synthetic. Synthetic errors are errors that
83-
carry little meaning by themselves. This may be because they are created at a central
84-
place (like a crash handler), and are all called the same: `Error`, `Segfault` etc.
85-
When the flag is set, Sentry will then try to use other information (top in-app frame
86-
function) rather than the exception type and value in the UI for the primary event display.
87-
Furthermore, if this flag is set, Sentry will ignore the exception `type` when grouping the
88-
exception into issues.
89-
: This flag should be set for all "segfaults" for instance as every single error group would
90-
look very similar otherwise. Also, errors the SDK creates to add a stack trace to events
91-
that don't have one themselves should be marked as `synthetic` (This happens, for example,
92-
when users set `attachStackTrace: true` and capture a string message via `captureException`
93-
or `captureMessage`.)
135+
Optional (`boolean`)
94136
95-
`exception_id`
137+
Flag indicating whether the user has handled the exception (for example, via `try ... catch`).
96138
97-
: An optional numeric value providing an ID for the exception relative
98-
to this specific event. The SDK should assign simple incrementing integers
99-
to each exception in the tree, starting with 0 for the root of the tree.
100-
In other words, when flattened into the list provided in the exception
101-
values on the event, the last exception in the list should have ID 0,
102-
the previous one should have ID 1, the next previous should have ID 2, etc.
139+
#### `description`
103140
104-
`parent_id`
141+
Optional (`string`)
105142
106-
: An optional numeric value pointing at the exception_id that is the
107-
parent of this exception. The SDK should assign this to all exceptions except
108-
the root exception (the last to be listed in the exception values).
143+
Human-readable description of the error mechanism and a possible hint on how to solve this error.
109144
110-
`is_exception_group`
145+
#### `help_link`
111146
112-
: An optional flag indicating that this exception is part of an exception group type specific to the platform or language.
147+
Optional (`string`)
113148
114-
`source`
149+
Fully qualified URL to an online help resource, possibly interpolated with error parameters.
115150
116-
: 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.
151+
#### `synthetic`
152+
153+
Optional (`boolean`)
154+
155+
Flag indicating that this error is synthetic.
156+
Synthetic errors are errors that carry little meaning by themselves.
157+
This may be because they are all created at a central place (like a crash handler), and share the same title: `Error`, `Segfault` etc.
158+
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.
159+
Furthermore, if this flag is set, Sentry will ignore the exception `type` when grouping the exception into issues.
160+
This flag SHOULD be set for all "segfaults" for instance as every single error group would look very similar otherwise.
161+
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`.)
162+
163+
#### `exception_id`
164+
165+
Optional (`number`)
166+
167+
An optional numeric value providing an ID for the exception relative to this specific event.
168+
The SDK SHOULD assign simple incrementing integers to each exception in the tree, starting with 0 for the root of the tree.
169+
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,
170+
the previous one SHOULD have ID 1, the next previous SHOULD have ID 2, etc.
171+
172+
#### `parent_id`
173+
174+
Optional (`number`)
175+
176+
An optional numeric value pointing at the exception_id that is the parent of this exception.
177+
The SDK SHOULD assign this to all exceptions except the root exception (the last to be listed in the exception values).
178+
179+
#### `is_exception_group`
180+
181+
Optional (`boolean`)
182+
183+
Flag indicating that this exception is part of an exception group type specific to the platform or language.
184+
185+
#### `source`
186+
187+
Optional (`string`)
188+
189+
An optional string value describing the source of the exception.
190+
The SDK SHOULD populate this with the name of the property or attribute of the parent exception that this exception was acquired from.
191+
In the case of an array, it SHOULD include the zero-based array index as well.
117192
118193
- Python Examples: `"__context__"`, `"__cause__"`, `"exceptions[0]"`, `"exceptions[1]"`
119194
- .NET Examples: `"InnerException"`, `"InnerExceptions[0]"`, `"InnerExceptions[1]"`
120195
- JavaScript Examples: `"cause"`, `"errors[0]"`, `"errors[1]"`
121196
122-
`meta`
123-
124-
: Optional information from the operating system or runtime on the exception
125-
mechanism (see [meta information](#meta-information)).
197+
#### `meta`
126198
127-
`data`
199+
Optional information from the operating system or runtime on the exception mechanism (see [meta information](#meta-information)).
128200
129-
: Arbitrary extra data that might help the user understand the error thrown by
130-
this mechanism.
201+
#### `data`
131202
132-
<Alert title="Note" level="warning">
133-
The <code>type</code> attribute is required to send any exception mechanism attribute, even
134-
if the SDK cannot determine the specific mechanism. In this case, set the <code>type</code>
135-
to <code>generic</code>. See below for an example.
136-
</Alert>
203+
Arbitrary extra data that might help the user understand the error thrown by this mechanism.
137204
138205
### Meta information
139206

0 commit comments

Comments
 (0)