You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: develop-docs/sdk/expected-features/index.mdx
+21-20Lines changed: 21 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,14 +4,15 @@ sidebar_order: 4
4
4
---
5
5
6
6
The following is a description of features that are commonly expected in Sentry SDKs. Make sure to also
7
-
have read the <Linkto="/sdk/unified-api">unified API design</Link> documentation
7
+
have read the <Linkto="/sdk/miscellaneous/unified-api">unified API design</Link> documentation
8
8
which explains the common API design.
9
9
10
10
## Background Sending
11
11
12
12
Events should be transmitted in a background thread or similar system. This queue must be flushed when the
13
13
application shuts down with a specific timeout. This feature is typically user facing and explained
14
-
as part of [shutdown and draining](https://docs.sentry.io/error-reporting/configuration/draining/?platform=swift).
14
+
as part of [shutdown and draining](https://docs.sentry.io/platforms/javascript/configuration/draining/).
15
+
15
16
16
17
## Uncaught Exception Handler
17
18
@@ -23,11 +24,11 @@ This behavior is typically provided by a default integration that can be disable
23
24
24
25
Scopes should be provided by SDKs to set common attributes and context data on events sent to Sentry emitted from the current scope. They should be inherited to lower scopes so that they can be set "globally" on startup. Note that some attributes can only be set in the client options (`release`, `environment`) and not on scopes.
25
26
26
-
What scope means depends on the application, for a web framework it is most likely a single request/response cycle. For a mobile application there is often just one single scope that represents the single user and their actions. Scoping can be difficult to implement because it often has to deal with threads or concurrency and can involve deep integration with frameworks. <Linkto="/sdk/unified-api#scope">see the scopes page</Link> for more information.
27
+
What scope means depends on the application, for a web framework it is most likely a single request/response cycle. For a mobile application there is often just one single scope that represents the single user and their actions. Scoping can be difficult to implement because it often has to deal with threads or concurrency and can involve deep integration with frameworks. <Linkto="/sdk/miscellaneous/unified-api#scope">see the scopes page</Link> for more information.
27
28
28
29
## Automatic Context Data
29
30
30
-
Automatic addition of useful attributes such as `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. Please check [Data Handling](/sdk/data-handling) for considerations.
31
+
Automatic addition of useful attributes such as `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. Please check [Data Handling](/sdk/expected-features/data-handling) for considerations.
31
32
32
33
## Breadcrumbs
33
34
@@ -41,7 +42,7 @@ With deeper framework integration, the automatic recording of breadcrumbs is pos
41
42
* System Events: low battery, low storage space, airplane mode started, memory warnings, device orientation changed, etc.
Respect Sentry’s HTTP 429 `Retry-After` header, or, if the SDK supports multiple payload types (e.g. errors and transactions), the `X-Sentry-Rate-Limits` header. Outgoing SDK requests should be dropped during the backoff period.
67
68
68
-
See <Linkto="/sdk/rate-limiting">Rate Limiting</Link> for details.
69
+
See <Linkto="/sdk/expected-features/rate-limiting">Rate Limiting</Link> for details.
69
70
70
71
71
72
## Backpressure Management
72
73
73
74
Backend SDKs (typically used in server applications) should have backpressure management logic that dynamically downsamples transactions when the throughput in the system is too high.
74
75
75
-
See <Linkto="/sdk/performance/backpressure">Backpressure Management</Link> for details.
76
+
See <Linkto="/sdk/telemetry/traces/backpressure/">Backpressure Management</Link> for details.
76
77
77
78
## In-App frames
78
79
@@ -98,7 +99,7 @@ Ability to get the ID of the last event sent. Event IDs are useful for correlati
98
99
99
100
## User Feedback
100
101
101
-
For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope](/sdk/envelopes/#user-feedback). Alternatively, the SDKs can
102
+
For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope item](/sdk/data-model/envelope-items/#user-feedback). Alternatively, the SDKs can
102
103
use the [User Feedback endpoint](https://docs.sentry.io/api/projects/submit-user-feedback/), which is not recommended.
103
104
104
105
### User Facing Platforms
@@ -130,7 +131,7 @@ Envelope item:
130
131
131
132
## Attachments
132
133
133
-
Attachments are files stored alongside an event. To send an attachment, add it as an [envelope item](/sdk/envelopes/#attachment)
134
+
Attachments are files stored alongside an event. To send an attachment, add it as an [envelope item](/sdk/data-model/envelope-items/#attachment)
134
135
to the corresponding event.
135
136
136
137
We recommend implementing two types of attachments, one with a path and another with a byte array.
@@ -142,7 +143,7 @@ The overload that takes a `path` should consider:
142
143
* If reading the attachment fails, the SDK should not drop the whole envelope, but just the attachment's envelope item.
143
144
* If the SDK is in debug mode log (`debug=true`) out errors to make debugging easier.
144
145
145
-
If the SDK supports [transactions](/sdk/envelopes/#transaction), the attachments should offer a flag `addToTransactions`,
146
+
If the SDK supports [transactions](/sdk/data-model/envelope-items/#transaction), the attachments should offer a flag `addToTransactions`,
146
147
that specifies if SDK adds the attachment to every transaction or not. The default should be `false`.
147
148
148
149
Use the implementations of [Java](https://github.com/getsentry/sentry-java/blob/main/sentry/src/main/java/io/sentry/Attachment.java),
@@ -158,7 +159,7 @@ useful because attachments could quickly eat up the users' disk space. Furthermo
158
159
159
160
## Screenshots
160
161
161
-
When the user opts-in, if technically possible, take a screenshot of the application during a crash or error and include it as an [attachment](#attachments) to the [envelope](/sdk/envelopes/) with the event.
162
+
When the user opts-in, if technically possible, take a screenshot of the application during a crash or error and include it as an [attachment](#attachments) to the [envelope](/sdk/data-model/envelopes/) with the event.
162
163
163
164
This feature only applies to SDKs with a user interface, such as Mobile and Desktop.
164
165
In some environments such as native iOS, taking a screenshot requires the UI thread and in the event of a crash, that might not be available. So inherently this feature will be a best effort solution.
@@ -209,7 +210,7 @@ Consider having the SDK retry sending events once the device is back online, whe
209
210
210
211
Once the device is back online, the SDK is likely going to empty its disk queue in a quick burst of requests. This can trigger different abuse filters in Sentry. To account for that, it's considered to add a small delay between cached event captures. A recommended value is 100 milliseconds.
211
212
212
-
If the SDK is being [rate-limited](/sdk/rate-limiting/), which causes the SDK to drop any event that reaches its HTTP transport, cosider stop consuming the disk cache until the `Retry-After` timeout is reached or the app restarts.
213
+
If the SDK is being [rate-limited](/sdk/expected-features/rate-limiting/), which causes the SDK to drop any event that reaches its HTTP transport, cosider stop consuming the disk cache until the `Retry-After` timeout is reached or the app restarts.
213
214
214
215
#### Example implementations
215
216
@@ -287,7 +288,7 @@ If Performance Monitoring is both supported by the SDK and enabled in the client
287
288
- HTTP requests must be enhanced with a [`sentry-trace` HTTP header](/sdk/performance/#header-sentry-trace) to support [distributed tracing](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing)
288
289
- HTTP requests must be enhanced with a [`traceparent` HTTP header](/sdk/performance/#header-traceparent) to support [distributed tracing](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing)
289
290
- HTTP requests must be enhanced with a [`baggage` HTTP header](/sdk/performance/dynamic-sampling-context/#baggage-header) to support [dynamic sampling](/sdk/performance/dynamic-sampling-context/)
290
-
- span status must match HTTP response status code ([see Span status to HTTP status code mapping](/sdk/event-payloads/span/))
291
+
- span status must match HTTP response status code ([see Span status to HTTP status code mapping](/sdk/data-model/event-payloads/span/))
291
292
- when network error occurs, span status must be set to `internal_error`
292
293
- span data must follow the [Span Data Conventions](/sdk/performance/span-data-conventions/)
293
294
@@ -308,9 +309,9 @@ The HTTP Client integration should have 3 configuration options:
308
309
309
310
The HTTP Client integration should capture error events with the following properties:
310
311
311
-
The Request interface, see the <Linkto="/sdk/event-payloads/request/">Spec</Link> for details.
312
+
The Request interface, see the <Linkto="/sdk/data-model/event-payloads/request/">Spec</Link> for details.
312
313
313
-
The Response context, see the <Linkto="/sdk/event-payloads/contexts/#response-context">Spec</Link> for details.
314
+
The Response context, see the <Linkto="/sdk/data-model/event-payloads/contexts/#response-context">Spec</Link> for details.
314
315
315
316
```json
316
317
{
@@ -329,12 +330,12 @@ The Response context, see the <Link to="/sdk/event-payloads/contexts/#response-c
329
330
}
330
331
```
331
332
332
-
The Exception Interface, see the <Linkto="/sdk/event-payloads/exception/">Spec</Link> for details.
333
+
The Exception Interface, see the <Linkto="/sdk/data-model/event-payloads/exception/">Spec</Link> for details.
333
334
334
335
If the HTTP Client integration does not throw an exception for unsuccessful requests, you can create a synthetic exception following this Spec:
335
336
336
-
- Set the <Linkto="/sdk/event-payloads/exception/#exception-mechanism">Exception Mechanism</Link> with a proper `type` such as `SentryOkHttpInterceptor`.
337
-
- Set the <Linkto="/sdk/event-payloads/stacktrace/">Stack Trace Interface</Link> with `snapshot=true`.
337
+
- Set the <Linkto="/sdk/data-model/event-payloads/exception/#exception-mechanism">Exception Mechanism</Link> with a proper `type` such as `SentryOkHttpInterceptor`.
338
+
- Set the <Linkto="/sdk/data-model/event-payloads/stacktrace/">Stack Trace Interface</Link> with `snapshot=true`.
338
339
-`HTTP Client Error with status code: $code`.
339
340
340
341
When capturing error events, pass the original `Request` and `Response` objects from the HTTP Client as `hints`, so the users may filter out events in `beforeSend` with the full context.
@@ -345,7 +346,7 @@ As an example, see the [OkHTTP Client integration](https://github.com/getsentry/
345
346
346
347
## GraphQL Client Integrations
347
348
348
-
The GraphQL Client integrations should match the guidelines for [HTTP Client Integrations](/sdk/features/#http-client-integrations) with a few differences:
349
+
The GraphQL Client integrations should match the guidelines for [HTTP Client Integrations](/sdk/expected-features/#http-client-integrations) with a few differences:
349
350
350
351
The `failedRequestStatusCodes` parameter does not exist because GraphQL errors are not HTTP errors, so that the request can be errored even though the HTTP status code of the response is successful.
351
352
@@ -412,7 +413,7 @@ The `fingerprints` field should be set to `["$operationName", "$operationType",
412
413
413
414
### Server
414
415
415
-
The GraphQL Performance integration should match the guidelines for [GraphQL Client Integrations](/sdk/features/#graphql-client-integrations) with a few differences:
416
+
The GraphQL Performance integration should match the guidelines for [GraphQL Client Integrations](/sdk/expected-features/#graphql-client-integrations) with a few differences:
416
417
417
418
The transaction's name should be set with the GraphQL operation name, if possible, otherwise fallback to something unique that makes sense, e.g. the canonical name of the actual/generated class.
0 commit comments