diff --git a/src/components/sidebar.tsx b/src/components/sidebar.tsx index 55a14e255d..7908328aa9 100644 --- a/src/components/sidebar.tsx +++ b/src/components/sidebar.tsx @@ -192,92 +192,90 @@ export default () => {
  • diff --git a/src/docs/analytics.mdx b/src/docs/analytics.mdx index dfc72eca4c..f45bedb289 100644 --- a/src/docs/analytics.mdx +++ b/src/docs/analytics.mdx @@ -8,7 +8,7 @@ This guide steps you through instrumenting your code with Sentry's 3rd-party ana [BigQuery](https://cloud.google.com/bigquery/) is a Google data warehouse that a lot of our data calls home. This includes all our analytics data and some (not all) production data that might be of interest when joins are necessary for answering richer, more complex questions. From sentry/getsentry, our data goes through [reload](https://github.com/getsentry/reload), our ETL for BigQuery. -As a general rule, do not add an analytic event if it has the potential to be triggered over 1,000,000 times/day. If this threshold is exceeded, it may cause the analytics service to crash. If you are unsure of how frequently the analytic event will be triggered, add it as a Datadog [metric](https://develop.sentry.dev/analytics/#metrics) first. +As a general rule, do not add an analytic event if it has the potential to be triggered over 1,000,000 times/day. If this threshold is exceeded, it may cause the analytics service to crash. If you are unsure of how frequently the analytic event will be triggered, add it as a Datadog [metric](/analytics/#metrics) first. ## Amplitude diff --git a/src/docs/database-migrations.mdx b/src/docs/database-migrations.mdx index c46d4a319d..9145a62a73 100644 --- a/src/docs/database-migrations.mdx +++ b/src/docs/database-migrations.mdx @@ -294,7 +294,7 @@ With postgres 14, columns can be added to tables of all sizes as deploy time migrations if you follow the guidelines on default values & allowing nulls. When creating new columns they should either be: -- Not null with a default. https://develop.sentry.dev/database-migrations/#adding-not-null-to-columns +- Not null with a default. [read more](/database-migrations/#adding-not-null-to-columns) - Created as nullable. If no default value can be set on the column, then it's best just to make it nullable. ### Adding Columns With a Default diff --git a/src/docs/dynamic-sampling/fidelity-and-biases.mdx b/src/docs/dynamic-sampling/fidelity-and-biases.mdx index 43675a12c8..2f1de2c2b7 100644 --- a/src/docs/dynamic-sampling/fidelity-and-biases.mdx +++ b/src/docs/dynamic-sampling/fidelity-and-biases.mdx @@ -45,7 +45,7 @@ A trace is a **collection of transactions that are related to each other**. For Trace sampling ensures that **either all transactions of a trace are sampled, or none**. That is, these rules **always yield the same sampling decision** for every transaction in the same trace. This requires the cooperation of SDKs and thus allows sampling only by `project`, `release`, `environment`, and `transaction` name. -To achieve trace sampling, SDKs pass all fields that can be sampled by [Dynamic Sampling Context (DSC)](/sdk/performance/dynamic-sampling-context/) (defined [here](https://getsentry.github.io/relay/relay_sampling/dsc/struct.DynamicSamplingContext.html)) as they propagate traces. _This ensures that every transaction from the same trace comes with the same DSC._ +To achieve trace sampling, SDKs pass all fields that can be sampled by [Dynamic Sampling Context (DSC)](/sdk/telemetry/tracing/dynamic-sampling-context/) (defined [here](https://getsentry.github.io/relay/relay_sampling/dsc/struct.DynamicSamplingContext.html)) as they propagate traces. _This ensures that every transaction from the same trace comes with the same DSC._ ![Trace Sampling](/images/traceSampling.png) diff --git a/src/docs/frontend/working-on-getting-started-docs.mdx b/src/docs/frontend/working-on-getting-started-docs.mdx index fe27fb2e32..d1b39396b4 100644 --- a/src/docs/frontend/working-on-getting-started-docs.mdx +++ b/src/docs/frontend/working-on-getting-started-docs.mdx @@ -46,7 +46,7 @@ The structure for the documentation is built on React and follows the following 1. Locate the language folder within [gettingStartedDocs](https://github.com/getsentry/sentry/tree/master/static/app/gettingStartedDocs). 2. Update the file `index.tsx` with the necessary changes. 3. You might need to update the tests present in the file `index.spec.tsx` -4. Finally, before concluding, please run Sentry locally or use the command `yarn dev-ui` [Frontend Development Server](https://develop.sentry.dev/frontend/development-server/) and perform a manual test to ensure that the getting started documentation renders correctly in both the onboarding process of a new organization and in the project creation flow. This step is essential for verifying the proper functioning and visual appearance of the documentation. +4. Finally, before concluding, please run Sentry locally or use the command `yarn dev-ui` [Frontend Development Server](/frontend/development-server/) and perform a manual test to ensure that the getting started documentation renders correctly in both the onboarding process of a new organization and in the project creation flow. This step is essential for verifying the proper functioning and visual appearance of the documentation. ### Framework diff --git a/src/docs/issue-platform-detectors.mdx b/src/docs/issue-platform-detectors.mdx index e9363bdff6..40bf2fbaec 100644 --- a/src/docs/issue-platform-detectors.mdx +++ b/src/docs/issue-platform-detectors.mdx @@ -68,7 +68,7 @@ Reporting circumstantial data is not useful! This is a crucial distinction betwe With every new issue type, we could be adding more and more noise to the Issues product. New issues fatigue is real for our customers. This is why it’s important to understand how a new detector you want to ship affects the overall noise of the Issue Stream. -Accurate detection of truly valuable problems and correct grouping can transform "noise" into "signal." Every detector should be evaluated against this standard. There is an option to [define a custom noise config](https://develop.sentry.dev/issue-platform/#register-an-issue-type) when creating a new detector. +Accurate detection of truly valuable problems and correct grouping can transform "noise" into "signal." Every detector should be evaluated against this standard. There is an option to [define a custom noise config](/issue-platform/#register-an-issue-type) when creating a new detector. # Development diff --git a/src/docs/issue-platform.mdx b/src/docs/issue-platform.mdx index ac8593e583..94f23a3301 100644 --- a/src/docs/issue-platform.mdx +++ b/src/docs/issue-platform.mdx @@ -145,7 +145,7 @@ The most current version of this schema is documented here: Schema -The event schema should match the Sentry event schema. Any fields/interfaces defined here can be passed along with your event. It's best to fill in as many of these as makes sense for your issue type. +The event schema should match the Sentry event schema. Any fields/interfaces defined here can be passed along with your event. It's best to fill in as many of these as makes sense for your issue type. There's a minimum set of fields which should be included: diff --git a/src/docs/philosophy.mdx b/src/docs/philosophy.mdx index 6266e890c6..f721bc7143 100644 --- a/src/docs/philosophy.mdx +++ b/src/docs/philosophy.mdx @@ -1,5 +1,5 @@ --- -title: "Development Philosophy" +title: Development Philosophy --- This document sets guidelines for how we approach software development at @@ -9,8 +9,7 @@ acquainted with the codebase, having this context will be valuable to understand how to approach things. This guidance only partially applies to SDKs, where slightly different rules -prevail. For that, please refer to the [SDK Philosophy and Design Principles -document](/sdk/philosophy/). +prevail. For that, please refer to the [SDK Philosophy](/sdk/fundamentals/philosophy/). ## Beware of Fancy Code @@ -155,8 +154,8 @@ older versions of a library than to go to the bleeding edge. That does not mean we don’t upgrade, but we recognize that this comes at a cost and needs to be considered. -For SDKs we are even stricter. For that, please refer to the [SDK Philosophy -and Design Principles document](/sdk/philosophy/). +For SDKs we are even stricter. For that, please refer to the [SDK Philosophy +document](/sdk/fundamentals/philosophy/). ## Branches and Pull Requests diff --git a/src/docs/sdk/endpoints/envelope.mdx b/src/docs/sdk/endpoints/envelope.mdx new file mode 100644 index 0000000000..ae0288c0ef --- /dev/null +++ b/src/docs/sdk/endpoints/envelope.mdx @@ -0,0 +1,6 @@ +--- +title: Envelope Endpoint +sidebar_order: 2 +--- + +See [Envelopes](/sdk/protocol/envelopes/). \ No newline at end of file diff --git a/src/docs/sdk/endpoints/index.mdx b/src/docs/sdk/endpoints/index.mdx new file mode 100644 index 0000000000..b31b01db07 --- /dev/null +++ b/src/docs/sdk/endpoints/index.mdx @@ -0,0 +1,6 @@ +--- +title: Endpoints +sidebar_order: 9000 +--- + + \ No newline at end of file diff --git a/src/docs/sdk/rate-limiting.mdx b/src/docs/sdk/endpoints/rate-limiting.mdx similarity index 96% rename from src/docs/sdk/rate-limiting.mdx rename to src/docs/sdk/endpoints/rate-limiting.mdx index 3260c5d199..28b95e1460 100644 --- a/src/docs/sdk/rate-limiting.mdx +++ b/src/docs/sdk/endpoints/rate-limiting.mdx @@ -1,6 +1,6 @@ --- -title: 'Rate Limiting' -sidebar_order: 5 +title: Rate Limiting +sidebar_order: 1 --- Rate limits are communicated to SDKs via status codes and response headers. For regular rate limit responses, we emit a [`429`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) status code and specify a [`Retry-After`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) header. @@ -15,7 +15,7 @@ Each *quota_limit* has the form `retry_after:categories:scope:reason_code:namesp - `retry_after`: Number of seconds (as an integer or a floating point number) until this rate limit expires. - `categories`: Semicolon-separated list of [data categories](https://github.com/getsentry/relay/blob/master/relay-base-schema/src/data_category.rs#L91). **If empty, this limit applies to all categories**. - While these categories might look similar to the [envelope item types](/sdk/envelopes/#data-model), they are not identical, and have slight differences. + While these categories might look similar to the [envelope item types](/sdk/protocol/envelopes/#data-model), they are not identical, and have slight differences. - `scope`: The scope that this limit applies to. Can be ignored by SDKs. - `reason_code`: A unique identifier for the quota hinting at the rate limiting reason. Can be ignored by SDKs. - `namespaces`: Semicolon-separated list of metric namespace identifiers. This will only be present if the rate limit applies to the `metric_bucket` data category. If the namespace is not present, the backoff applies to all metrics. @@ -83,7 +83,7 @@ Guidelines for how SDKs should determine the current rate limits: As stated earlier, SDKs can ignore the `scope` dimension. These definitions are here as a suplement to explain what the `X-Sentry-Rate-Limits` header is made of. - **Category:** Classifies the type of data that is being counted. Arbitrary categories can be added as long as they can be inferred from the event or data being ingested. -While these [data categories](https://github.com/getsentry/relay/blob/master/relay-base-schema/src/data_category.rs#L91) might look similar to the [envelope item types](/sdk/envelopes/#data-model), they are not identical, and have slight differences. +While these [data categories](https://github.com/getsentry/relay/blob/master/relay-base-schema/src/data_category.rs#L91) might look similar to the [envelope item types](/sdk/protocol/envelopes/#data-model), they are not identical, and have slight differences. - `default`: Events with an event_type not listed explicitly below. - `error`: Error events. - `transaction`: Transaction type events. diff --git a/src/docs/sdk/store.mdx b/src/docs/sdk/endpoints/store.mdx similarity index 96% rename from src/docs/sdk/store.mdx rename to src/docs/sdk/endpoints/store.mdx index b01e7f8479..b9e83d26ab 100644 --- a/src/docs/sdk/store.mdx +++ b/src/docs/sdk/endpoints/store.mdx @@ -1,11 +1,11 @@ --- title: Store Endpoint -sidebar_order: 50 +sidebar_order: 3 --- -The `/store` endpoint is deprecated. All data should be sent to the `/envelope` endpoint. See [Envelopes](/sdk/envelopes/). +The `/store` endpoint is deprecated. All data should be sent to the `/envelope` endpoint. See [Envelopes](/sdk/protocol/envelopes/). @@ -43,7 +43,7 @@ between them is that attributes are very barebones key/value pairs (for the most part) and interfaces are rich styled interface elements. Examples of attribute are `event_id` or `tags` whereas the `exception` key is an interface. -For a list of all supported attributes and interfaces in event payloads, see Event Payloads. +For a list of all supported attributes and interfaces in event payloads, see Event Payloads. ## HTTP Headers diff --git a/src/docs/sdk/features.mdx b/src/docs/sdk/features.mdx index 859b09ff2e..a4613b1d2a 100644 --- a/src/docs/sdk/features.mdx +++ b/src/docs/sdk/features.mdx @@ -41,7 +41,7 @@ With deeper framework integration, the automatic recording of breadcrumbs is pos * System Events: low battery, low storage space, airplane mode started, memory warnings, device orientation changed, etc. * [Outgoing HTTP requests](#http-client-integrations) -Check out the [complete breadcrumb documentation](https://develop.sentry.dev/sdk/event-payloads/breadcrumbs/#breadcrumb-types) for more types. +Check out the [complete breadcrumb documentation](/sdk/protocol/event-payloads/breadcrumbs/#breadcrumb-types) for more types. ## Event Sampling @@ -65,14 +65,14 @@ ignore_transactions = ['GET /api/health','/api/v1/*'] 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. -See Rate Limiting for details. +See Rate Limiting for details. ## Backpressure Management 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. -See Backpressure Management for details. +See Backpressure Management for details. ## In-App frames @@ -98,7 +98,7 @@ Ability to get the ID of the last event sent. Event IDs are useful for correlati ## User Feedback -For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope](/sdk/envelopes/#user-feedback). Alternatively, the SDKs can +For all SDKs, it is strongly recommended to send the `User Feedback` as an [envelope](/sdk/protocol/envelopes/#user-feedback). Alternatively, the SDKs can use the [User Feedback endpoint](https://docs.sentry.io/api/projects/submit-user-feedback/), which is not recommended. ### User Facing Platforms @@ -130,7 +130,7 @@ Envelope item: ## Attachments -Attachments are files stored alongside an event. To send an attachment, add it as an [envelope item](/sdk/envelopes/#attachment) +Attachments are files stored alongside an event. To send an attachment, add it as an [envelope item](/sdk/protocol/envelopes/#attachment) to the corresponding event. We recommend implementing two types of attachments, one with a path and another with a byte array. @@ -142,7 +142,7 @@ The overload that takes a `path` should consider: * If reading the attachment fails, the SDK should not drop the whole envelope, but just the attachment's envelope item. * If the SDK is in debug mode log (`debug=true`) out errors to make debugging easier. -If the SDK supports [transactions](/sdk/envelopes/#transaction), the attachments should offer a flag `addToTransactions`, +If the SDK supports [transactions](/sdk/protocol/envelopes/#transaction), the attachments should offer a flag `addToTransactions`, that specifies if SDK adds the attachment to every transaction or not. The default should be `false`. Use the implementations of [Java](https://github.com/getsentry/sentry-java/blob/main/sentry/src/main/java/io/sentry/Attachment.java), @@ -158,7 +158,7 @@ useful because attachments could quickly eat up the users' disk space. Furthermo ## Screenshots -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. +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/protocol/envelopes/) with the event. This feature only applies to SDKs with a user interface, such as Mobile and Desktop. 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 +209,7 @@ Consider having the SDK retry sending events once the device is back online, whe 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. -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. +If the SDK is being [rate-limited](/sdk/endpoints/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. #### Example implementations @@ -280,12 +280,12 @@ If Performance Monitoring is both supported by the SDK and enabled in the client - operation: `http.client` - description: `$METHOD $url` (uppercase HTTP method), e.g. `GET https://sentry.io` -- 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) -- 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) -- 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/) -- span status must match HTTP response status code ([see Span status to HTTP status code mapping](/sdk/event-payloads/span/)) +- HTTP requests must be enhanced with a [`sentry-trace` HTTP header](/sdk/telemetry/tracing/#header-sentry-trace) to support [distributed tracing](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing) +- HTTP requests must be enhanced with a [`traceparent` HTTP header](/sdk/telemetry/tracing/#header-traceparent) to support [distributed tracing](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing) +- HTTP requests must be enhanced with a [`baggage` HTTP header](/sdk/telemetry/tracing/dynamic-sampling-context/#baggage-header) to support [dynamic sampling](/sdk/telemetry/tracing/dynamic-sampling-context/) +- span status must match HTTP response status code ([see Span status to HTTP status code mapping](/sdk/protocol/event-payloads/span/)) - when network error occurs, span status must be set to `internal_error` -- span data must follow the [Span Data Conventions](/sdk/performance/span-data-conventions/) +- span data must follow the [Span Data Conventions](/sdk/telemetry/tracing/span-data-conventions/) ### HTTP Client Errors @@ -298,15 +298,15 @@ The HTTP Client integration should have 3 configuration options: - `failedRequestStatusCodes` defaults to `500 - 599`, this configuration option accepts a `List` of `HttpStatusCodeRange` which is a range of HTTP status code -> `min` to `max` or a single `status_code`. - The SDK will only capture HTTP Client errors if the HTTP Response status code is within the defined ranges in `failedRequestStatusCodes`. - If the language has a `Range` type, it should be used instead of `HttpStatusCodeRange`. -- `failedRequestTargets` defaults to (`.*`), this configuration option accepts a `List` of `String` that may be Regular expressions as well, similar to tracePropagationTargets. +- `failedRequestTargets` defaults to (`.*`), this configuration option accepts a `List` of `String` that may be Regular expressions as well, similar to tracePropagationTargets. - The SDK will only capture HTTP Client errors if the HTTP Request URL is a match for any of the `failedRequestsTargets`. - sensitive `headers` should only be set if `sendDefaultPii` is enabled, e.g. `Cookie` and `Set-Cookie`. The HTTP Client integration should capture error events with the following properties: -The Request interface, see the Spec for details. +The Request interface, see the Spec for details. -The Response context, see the Spec for details. +The Response context, see the Spec for details. ```json { @@ -325,12 +325,12 @@ The Response context, see the Spec for details. +The Exception Interface, see the Spec for details. If the HTTP Client integration does not throw an exception for unsuccessful requests, you can create a synthetic exception following this Spec: -- Set the Exception Mechanism with a proper `type` such as `SentryOkHttpInterceptor`. -- Set the Stack Trace Interface with `snapshot=true`. +- Set the Exception Mechanism with a proper `type` such as `SentryOkHttpInterceptor`. +- Set the Stack Trace Interface with `snapshot=true`. - `HTTP Client Error with status code: $code`. 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. @@ -426,9 +426,9 @@ Spans should be created for [resolvers](https://www.apollographql.com/docs/apoll Spans should be created for [data loaders](https://graphql.org/learn/best-practices/#server-side-batching-caching/), if possible. -The operation type should follow the [Span Operation Conventions](/sdk/performance/span-operations/). +The operation type should follow the [Span Operation Conventions](/sdk/telemetry/tracing/span-operations/). -Extra (`data`) attributes for transactions and/or spans, there are [Span Data](/sdk/performance/span-data-conventions/) and [OTel GraphQL](https://opentelemetry.io/docs/specs/otel/trace/semantic_conventions/instrumentation/graphql/) conventions. +Extra (`data`) attributes for transactions and/or spans, there are [Span Data](/sdk/telemetry/tracing/span-data-conventions/) and [OTel GraphQL](https://opentelemetry.io/docs/specs/otel/trace/semantic_conventions/instrumentation/graphql/) conventions. Instrumenting APM for GraphQL will depend on the instrumented GraphQL library, if there are available hooks for it, the SDK should use them, otherwise, the SDK could try to monkeypatch the library or instrument the transport layer using heuristics, for example, if the URL ends with `graphql`, if there are HTTP Headers, etc. diff --git a/src/docs/sdk/hub_and_scope_refactoring.mdx b/src/docs/sdk/fundamentals/data-handling/context-management/hub_and_scope_refactoring.mdx similarity index 94% rename from src/docs/sdk/hub_and_scope_refactoring.mdx rename to src/docs/sdk/fundamentals/data-handling/context-management/hub_and_scope_refactoring.mdx index d0f5ae47fe..047c1909ac 100644 --- a/src/docs/sdk/hub_and_scope_refactoring.mdx +++ b/src/docs/sdk/fundamentals/data-handling/context-management/hub_and_scope_refactoring.mdx @@ -1,12 +1,14 @@ +--- +title: Hub & Scope Refactoring +--- + This is work in progress. Development has started in JS and Python, but we are still ironing out the wrinkles. -# Hub & Scope Refactoring - -Historically Sentry's SDKs implemented the Hubs and Scopes models, a major defining aspect of the Unified API. This introduced a lot of complexity in a user facing manner, allowed more room for error from the user as well as SDK maintainers. Since looking at adopting OpenTelemetry "packages", to replace or in addition to, our existing performance packages in SDKs, there is a forcing factor. Sentry's model being different to OpenTelemetry's prevents us from supporting OpenTelemetry. +Historically Sentry's SDKs implemented the Hubs and Scopes models, a major defining aspect of the Unified API. This introduced a lot of complexity in a user facing manner, allowed more room for error from the user as well as SDK maintainers. Since looking at adopting OpenTelemetry "packages", to replace or in addition to, our existing performance packages in SDKs, there is a forcing factor. Sentry's model being different to OpenTelemetry's prevents us from supporting OpenTelemetry. ## A) Why Are We Doing This? @@ -22,7 +24,7 @@ This is necessary because the Sentry SDKs should be able to capture all spans fr ### Make Sentry Performance Instrumentation Easier -Hubs and scopes is a complicated system, that can easily be misused (also see [here](https://develop.sentry.dev/sdk/research/performance/#scope-propagation)). It requires us to create new hubs which in turn breaks breadcrumbs and other features. For the future we want to have one consistent system, that is easy to understand and use. +Hubs and scopes is a complicated system, that can easily be misused (also see [here](/sdk/telemetry/tracing/research-performance-api/#scope-propagation)). It requires us to create new hubs which in turn breaks breadcrumbs and other features. For the future we want to have one consistent system, that is easy to understand and use. --- @@ -133,7 +135,7 @@ We should make it very clear in the changelog that top level API only writes to ## E) Implementation Details -We will merge the functionality of the `Hub` and the `Scope` of the Unified API into the `Scope` and we will remove the `Hub`. We will add some new APIs that make it easier for the user to do custom instrumentation. We will update our auto instrumentation to fork a scope whenever a new span is created. This aligns us with what OTel does. +We will merge the functionality of the `Hub` and the `Scope` of the Unified API into the `Scope` and we will remove the `Hub`. We will add some new APIs that make it easier for the user to do custom instrumentation. We will update our auto instrumentation to fork a scope whenever a new span is created. This aligns us with what OTel does. TODO: add where the propagation context is stored and applied, add how tracing without performance works, where spans/transactions live and other problems we discovered and solved in implementing this in the first two SDKs. diff --git a/src/docs/sdk/fundamentals/data-handling/context-management/index.mdx b/src/docs/sdk/fundamentals/data-handling/context-management/index.mdx new file mode 100644 index 0000000000..b054d4db45 --- /dev/null +++ b/src/docs/sdk/fundamentals/data-handling/context-management/index.mdx @@ -0,0 +1,5 @@ +--- +title: Context Management +--- + + \ No newline at end of file diff --git a/src/docs/sdk/new-scopes-api.png b/src/docs/sdk/fundamentals/data-handling/context-management/new-scopes-api.png similarity index 100% rename from src/docs/sdk/new-scopes-api.png rename to src/docs/sdk/fundamentals/data-handling/context-management/new-scopes-api.png diff --git a/src/docs/sdk/data-handling.mdx b/src/docs/sdk/fundamentals/data-handling/index.mdx similarity index 95% rename from src/docs/sdk/data-handling.mdx rename to src/docs/sdk/fundamentals/data-handling/index.mdx index 0659faab2a..dc9ddaa30a 100644 --- a/src/docs/sdk/data-handling.mdx +++ b/src/docs/sdk/fundamentals/data-handling/index.mdx @@ -31,7 +31,7 @@ All other platforms require the event to include `user.ip={{auto}}` which happen Before sending events to Sentry, the SDKs should invokes callbacks. That allows users to remove any sensitive data client-side. -- [`before-send` and `event-processors`](https://develop.sentry.dev/sdk/unified-api/#static-api) can be used to register a callback with custom logic to remove sensitive data. +- [`before-send` and `event-processors`](/sdk/fundamentals/unified-api/#static-api) can be used to register a callback with custom logic to remove sensitive data. ### Application State @@ -118,5 +118,5 @@ Fields in the event payload that allow user-specified or dynamic values are rest Additionally, size limits apply to all store requests for the total size of the request, event payload, and attachments. Sentry rejects all requests exceeding these limits. Please refer the following resources for the exact size limits: -- Envelope Endpoint Size Limits -- Store Endpoint Size Limits +- Envelope Endpoint Size Limits +- Store Endpoint Size Limits diff --git a/src/docs/sdk/fundamentals/index.mdx b/src/docs/sdk/fundamentals/index.mdx new file mode 100644 index 0000000000..a05eea5c0f --- /dev/null +++ b/src/docs/sdk/fundamentals/index.mdx @@ -0,0 +1,5 @@ +--- +title: Fundamentals +--- + + \ No newline at end of file diff --git a/src/docs/sdk/philosophy.mdx b/src/docs/sdk/fundamentals/philosophy/index.mdx similarity index 98% rename from src/docs/sdk/philosophy.mdx rename to src/docs/sdk/fundamentals/philosophy/index.mdx index 206ec394b9..1defb4b188 100644 --- a/src/docs/sdk/philosophy.mdx +++ b/src/docs/sdk/fundamentals/philosophy/index.mdx @@ -1,6 +1,6 @@ --- -title: Philosophy and Design Principles -sidebar_order: 0 +title: Philosophy +sidebar_order: 1 --- This document sets some general guidances for how to approach SDK development at Sentry. It should aid both internal and external developers to understand what motivations go into the design of the SDKs and why we're deciding in certain ways. diff --git a/src/docs/sdk/fundamentals/reliability/index.mdx b/src/docs/sdk/fundamentals/reliability/index.mdx new file mode 100644 index 0000000000..2a45fb0aef --- /dev/null +++ b/src/docs/sdk/fundamentals/reliability/index.mdx @@ -0,0 +1,8 @@ +--- +title: Reliability +sidebar_order: 3 +--- + +Reliable systems are designed and implemented in a way so they can withstand failures, maintain high levels of performance, and recover quickly from disruptions. + + \ No newline at end of file diff --git a/src/docs/sdk/fundamentals/reliability/resiliency/index.mdx b/src/docs/sdk/fundamentals/reliability/resiliency/index.mdx new file mode 100644 index 0000000000..1048bdfc4c --- /dev/null +++ b/src/docs/sdk/fundamentals/reliability/resiliency/index.mdx @@ -0,0 +1,7 @@ +--- +title: Resiliency +--- + +Resiliency is the ability of a system to gracefully handle and recover from failures, both inadvertent and malicious. + + \ No newline at end of file diff --git a/src/docs/sdk/signal-handlers.mdx b/src/docs/sdk/fundamentals/reliability/resiliency/signal-handlers.mdx similarity index 96% rename from src/docs/sdk/signal-handlers.mdx rename to src/docs/sdk/fundamentals/reliability/resiliency/signal-handlers.mdx index 79871e38ae..1d8302a499 100644 --- a/src/docs/sdk/signal-handlers.mdx +++ b/src/docs/sdk/fundamentals/reliability/resiliency/signal-handlers.mdx @@ -9,7 +9,7 @@ This applies to mobile SDKs as well as the native SDK. As signal handlers are notoriously difficult to work with and the restrictions placed on us are quite limiting we have to partially bend the rules of what is acceptable. -# General Risks +## General Risks The general risks with signal handlers stem from the interruptive nature: @@ -25,7 +25,7 @@ theory you can only call [async safe functions](https://man7.org/linux/man-pages which unfortunately put a lot of limitations in place. In particular not even allocations are possible, let alone most threading functions. -# Basic Recommendations +## Basic Recommendations We want to optimize our outcomes for getting good crash reports and getting crash reports altogether. We do not necessarily optimize for not crashing if @@ -49,7 +49,7 @@ disk in reducing priority. If for instance we can only collect auxiliary information with the risk of crashing in the crash handler, that one should be extracted and dumped after the stack trace has been created. -# Memory Allocation +### Memory Allocation The recommendation is for libraries to use custom allocation functions which under normal circumstances use `malloc` but after once have entered a crashing @@ -57,7 +57,7 @@ situation in the signal handler switch over to a bump allocator. This is necessary as malloc can (and will!) hold a lock when entering into a signal handler which can cause us to either dead lock or crash. -# Locks and Signal Handler Marking +### Locks and Signal Handler Marking Another issues is that we cannot generally use locks properly once in signal handlers. The way the native SDK is dealing with this situation is to @@ -66,7 +66,7 @@ generic code that might be wanting to wait for a real lock can either additionally block on the spinlock or silently pass if it's in the same thread as the signal handler. -# Writing Files +### Writing Files For writing files the `fwrite` family of functions must not be used as they are not async safe. Instead, the underlying `write` and `open` functions diff --git a/src/docs/sdk/unified-api/index.mdx b/src/docs/sdk/fundamentals/unified-api/index.mdx similarity index 98% rename from src/docs/sdk/unified-api/index.mdx rename to src/docs/sdk/fundamentals/unified-api/index.mdx index 9d7450c4e8..cd776da7d0 100644 --- a/src/docs/sdk/unified-api/index.mdx +++ b/src/docs/sdk/fundamentals/unified-api/index.mdx @@ -1,5 +1,6 @@ --- -title: 'Unified API' +title: Unified API +sidebar_order: 2 --- @@ -61,7 +62,7 @@ meant that certain integrations (such as breadcrumbs) were often not possible. - **client options**: Are parameters that are language and runtime specific and used to configure the client. This can be release and environment but also things like which integrations to configure, how in-app works etc. -- **context**: Contexts give extra data to Sentry. There are the special contexts (user and similar) and the generic ones (`runtime`, `os`, `device`), etc. Check out Contexts for valid keys. *Note: In older SDKs, you might encounter an unrelated concept of context, which is now deprecated by scopes* +- **context**: Contexts give extra data to Sentry. There are the special contexts (user and similar) and the generic ones (`runtime`, `os`, `device`), etc. Check out Contexts for valid keys. *Note: In older SDKs, you might encounter an unrelated concept of context, which is now deprecated by scopes* - **tags**: Tags can be arbitrary string→string pairs by which events can be searched. Contexts are converted into tags. diff --git a/src/docs/sdk/unified-api/unified-api.excalidraw b/src/docs/sdk/fundamentals/unified-api/unified-api.excalidraw similarity index 100% rename from src/docs/sdk/unified-api/unified-api.excalidraw rename to src/docs/sdk/fundamentals/unified-api/unified-api.excalidraw diff --git a/src/docs/sdk/unified-api/unified-api.png b/src/docs/sdk/fundamentals/unified-api/unified-api.png similarity index 100% rename from src/docs/sdk/unified-api/unified-api.png rename to src/docs/sdk/fundamentals/unified-api/unified-api.png diff --git a/src/docs/sdk/index.mdx b/src/docs/sdk/index.mdx index 3a6053612b..8c9900bb7f 100644 --- a/src/docs/sdk/index.mdx +++ b/src/docs/sdk/index.mdx @@ -1,22 +1,76 @@ --- -title: "SDK Development" +title: SDK Development --- The following is a guide for implementing a new Sentry SDK based on the new Unified API.
    It covers the protocol for event submission as well as guidelines for how clients should typically look and behave. -- Overview -- Philosophy and Design Principles -- Development Basics -- Data Handling -- Unified API -- Hub & Scope Refactoring/ - Expected Features -- Event Payloads -- Store Endpoint -- Envelopes -- Sessions -- Client Reports -- Profiles -- Setup Wizards + +
      +
    • Fundamentals +
        +
      • Philosophy
        • +
      • Unified API
        • +
      • + Data Handling +
          +
        • Context Management +
            +
          • Hubs & Scopes Refactoring
            • +
          +
          • +
        +
        • +
      • + Reliability +
          +
        • + Resiliency +
            +
          • Signal Handlers
            • +
          +
          • +
        +
        • +
      +
      • +
    • Telemetry +
        +
      • Tracing
        • +
      • Profiles
        • +
      • Metrics
        • +
      • Check-Ins
        • +
      +
      • +
    • Protocol +
        +
      • Envelopes
        • +
      • Event Payloads
        • +
      • Client Reports
        • +
      • Sessions
        • +
      +
      • +
    • Endpoints +
        +
      • Rate Limiting
        • +
      • Envelope Endpoint
        • +
      • Store Endpoint
        • +
      +
      • +
    • Tooling +
        +
      • Setup Wizards
        • +
      • Spotlight
        • +
      +
      • +
    • Processes +
        +
      • Onboarding
        • +
      • Development
        • +
      • Testing
        • +
      • Releasing
        • +
      +
      • +
    diff --git a/src/docs/sdk/performance/modules/index.mdx b/src/docs/sdk/performance/modules/index.mdx deleted file mode 100644 index ee25e3e524..0000000000 --- a/src/docs/sdk/performance/modules/index.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: 'Insights Modules' ---- - -The list below contains SDK documentation for our various Insights Modules (formerly known as "Peformance Modules"). - -- [App Starts](/sdk/performance/modules/app-starts/) -- [Caches](/sdk/performance/modules/caches/) -- [LLM Monitoring](/sdk/performance/modules/llm-monitoring/) -- [Queues](/sdk/performance/modules/queues/) -- [Queries](/sdk/performance/modules/queries/) -- [Requests](/sdk/performance/modules/requests/) -- [Assets](/sdk/performance/modules/assets/) -- [Screen Loads](/sdk/performance/modules/screen-loads/) -- [Web Vitals](/sdk/performance/modules/web-vitals/) diff --git a/src/docs/sdk/basics.mdx b/src/docs/sdk/processes/development/index.mdx similarity index 83% rename from src/docs/sdk/basics.mdx rename to src/docs/sdk/processes/development/index.mdx index 9ed6857fe5..ca6fe23b62 100644 --- a/src/docs/sdk/basics.mdx +++ b/src/docs/sdk/processes/development/index.mdx @@ -1,6 +1,6 @@ --- -title: Development Basics -sidebar_order: 2 +title: Development +sidebar_order: 10 --- So you want to develop an SDK? Before you get started here are some basics that are @@ -35,11 +35,6 @@ When sending events just substitute `orgXXX.ingest.sentry.io` with `localhost:30 whichever port you ended up chosing. Also note that a local relay will out of the box be available via HTTP only so don't try to send HTTPS requests there. -Join the SDK maintainers channel on Discord ---------------------- - -You can reach out to Sentry open source contributors and find other SDK maintainers in the [Sentry Discord server](https://discord.gg/sentry). Make sure to say hi on `#sdk-maintainers`. - Consult Existing SDKs --------------------- diff --git a/src/docs/sdk/overview.mdx b/src/docs/sdk/processes/development/overview.mdx similarity index 97% rename from src/docs/sdk/overview.mdx rename to src/docs/sdk/processes/development/overview.mdx index 247fc92d48..a20432f223 100644 --- a/src/docs/sdk/overview.mdx +++ b/src/docs/sdk/processes/development/overview.mdx @@ -28,7 +28,7 @@ Additionally, the following features are highly encouraged: - Non-blocking event submission - Context data helpers (e.g. setting the current user, recording breadcrumbs) - Event sampling -- Honor Sentry’s Rate Limiting HTTP headers +- Honor Sentry’s Rate Limiting HTTP headers - Pre and Post event send hooks - Local variable values in stack trace (on platforms where this is possible) - Send an `environment` on each event. If none was detected or set by the user, `production` should be used. @@ -119,7 +119,7 @@ All segments, including PROJECT_ID, are of type String. Sentry provides the following endpoints: -- /envelope/ for any submission using Envelopes. +- /envelope/ for any submission using Envelopes. - /store/ for plain JSON event submission. - [`/minidump/`](https://docs.sentry.io/platforms/native/minidump/) for multipart requests containing Minidumps. - [`/unreal/`](https://docs.sentry.io/platforms/native/ue4/) for Unreal @@ -201,7 +201,7 @@ it’s possible to send these values via the querystring: : The unix timestamp representing the time at which this event was generated.
    *This key is effectively deprecated, and it is ignored on the receiving side. - Use the [`sent_at` envelope header](/sdk/envelopes/#envelope-headers) instead.* + Use the [`sent_at` envelope header](/sdk/protocol/envelopes/#envelope-headers) instead.* `sentry_secret` diff --git a/src/docs/sdk/serverless/aws-lambda-lifecycle.png b/src/docs/sdk/processes/development/serverless/aws-lambda-lifecycle.png similarity index 100% rename from src/docs/sdk/serverless/aws-lambda-lifecycle.png rename to src/docs/sdk/processes/development/serverless/aws-lambda-lifecycle.png diff --git a/src/docs/sdk/serverless/aws-lambda.mdx b/src/docs/sdk/processes/development/serverless/aws-lambda.mdx similarity index 95% rename from src/docs/sdk/serverless/aws-lambda.mdx rename to src/docs/sdk/processes/development/serverless/aws-lambda.mdx index 14f63e4609..71413eb819 100644 --- a/src/docs/sdk/serverless/aws-lambda.mdx +++ b/src/docs/sdk/processes/development/serverless/aws-lambda.mdx @@ -44,7 +44,9 @@ to various AWS regions to be close to the users. Both these layers include the latest Sentry Javascript SDK (or Python SDK). -### Building of the Python Layer +### Python Layer + +#### Building The contents of the Layer directory for the Python layer are built during the "CI" workflow in Github actions. The steps necessary can be found @@ -53,7 +55,7 @@ The contents of the Layer directory for the Python layer are built during the This will prepare the Lambda layer directory, compress everything and upload the resulting zip file as an artifact to GitHub. -### Deployment of the Python Layer +#### Deployment The zip file prepared in the previous step will be deployed to AWS Lambda by [Craft](https://github.com/getsentry/craft).The configuration of craft for doing @@ -62,7 +64,9 @@ this can be found [here](https://github.com/getsentry/sentry-python/blob/master/ To deploy a new version of the Lambda layer to AWS, you need to trigger a new release of the Python SDK. -### Building of the Javascript/Node Layer +### Node.js Layer + +#### Building The contents of the Layer directory for the Javascript/Node layer are built during the "Build & Test" workflow in Github actions. The steps necessary can be found @@ -71,7 +75,7 @@ The contents of the Layer directory for the Javascript/Node layer are built duri This will prepare the Lambda layer directory, compress everything and upload the resulting zip file as an artifact to GitHub. -### Deployment of the Javascript/Node Layer +#### Deployment The zip file prepared in the previous step will be deployed to AWS Lambda by [Craft](https://github.com/getsentry/craft). The configuration of craft for doing diff --git a/src/docs/sdk/serverless/index.mdx b/src/docs/sdk/processes/development/serverless/index.mdx similarity index 54% rename from src/docs/sdk/serverless/index.mdx rename to src/docs/sdk/processes/development/serverless/index.mdx index 6867661a1c..454bff0565 100644 --- a/src/docs/sdk/serverless/index.mdx +++ b/src/docs/sdk/processes/development/serverless/index.mdx @@ -5,4 +5,4 @@ sidebar_order: 30 Welcome to serverless land! -- [AWS Lambda](/sdk/serverless/aws-lambda/) +- [AWS Lambda](/sdk/processes/development/serverless/aws-lambda/) diff --git a/src/docs/sdk/processes/index.mdx b/src/docs/sdk/processes/index.mdx new file mode 100644 index 0000000000..5fb34aa4f8 --- /dev/null +++ b/src/docs/sdk/processes/index.mdx @@ -0,0 +1,6 @@ +--- +title: Processes +sidebar_order: 9000 +--- + + \ No newline at end of file diff --git a/src/docs/sdk/processes/onboarding/index.mdx b/src/docs/sdk/processes/onboarding/index.mdx new file mode 100644 index 0000000000..69fbea949b --- /dev/null +++ b/src/docs/sdk/processes/onboarding/index.mdx @@ -0,0 +1,8 @@ +--- +title: Onboarding +sidebar_order: 1 +--- + +## Join the SDK maintainers channel on Discord + +You can reach out to Sentry open source contributors and find other SDK maintainers in the [Sentry Discord server](https://discord.gg/sentry). Make sure to say hi on `#sdk-maintainers`. diff --git a/src/docs/sdk/craft-quick-start.mdx b/src/docs/sdk/processes/releasing/index.mdx similarity index 99% rename from src/docs/sdk/craft-quick-start.mdx rename to src/docs/sdk/processes/releasing/index.mdx index bfc22ad70f..e60df84d04 100644 --- a/src/docs/sdk/craft-quick-start.mdx +++ b/src/docs/sdk/processes/releasing/index.mdx @@ -1,5 +1,6 @@ --- -title: "Craft Quick Start" +title: Releasing +sidebar_order: 30 --- This guide goes over the minimal setup needed to publish something via diff --git a/src/docs/sdk/processes/testing/index.mdx b/src/docs/sdk/processes/testing/index.mdx new file mode 100644 index 0000000000..fd6a8bf4d5 --- /dev/null +++ b/src/docs/sdk/processes/testing/index.mdx @@ -0,0 +1,6 @@ +--- +title: Testing +sidebar_order: 20 +--- + + \ No newline at end of file diff --git a/src/docs/sdk/processes/testing/integration-tests/index.mdx b/src/docs/sdk/processes/testing/integration-tests/index.mdx new file mode 100644 index 0000000000..54cc317fce --- /dev/null +++ b/src/docs/sdk/processes/testing/integration-tests/index.mdx @@ -0,0 +1,5 @@ +--- +title: Integration Tests +sidebar_order: 20 +--- + diff --git a/src/docs/sdk/processes/testing/load-testing/index.mdx b/src/docs/sdk/processes/testing/load-testing/index.mdx new file mode 100644 index 0000000000..c28697c2fa --- /dev/null +++ b/src/docs/sdk/processes/testing/load-testing/index.mdx @@ -0,0 +1,5 @@ +--- +title: Load Testing +sidebar_order: 30 +--- + diff --git a/src/docs/sdk/processes/testing/unit-tests/index.mdx b/src/docs/sdk/processes/testing/unit-tests/index.mdx new file mode 100644 index 0000000000..82f3fcf14a --- /dev/null +++ b/src/docs/sdk/processes/testing/unit-tests/index.mdx @@ -0,0 +1,5 @@ +--- +title: Unit Tests +sidebar_order: 10 +--- + diff --git a/src/docs/sdk/client-reports.mdx b/src/docs/sdk/protocol/client-reports.mdx similarity index 99% rename from src/docs/sdk/client-reports.mdx rename to src/docs/sdk/protocol/client-reports.mdx index ea652f53f9..b0ed36a259 100644 --- a/src/docs/sdk/client-reports.mdx +++ b/src/docs/sdk/protocol/client-reports.mdx @@ -1,6 +1,6 @@ --- title: Client Reports -sidebar_order: 20 +sidebar_order: 90 --- ## Scope and Intent @@ -85,7 +85,7 @@ will assume the current UTC timestamp. In the data model, this is called : _List of outcome objects_ {`reason`, `category`, `quantity`} - `reason`: A string reason that defines why events were lost. -- `category`: The data category for which the discard reason applies. These are the same data categories used for [rate limits](/sdk/rate-limiting/#definitions). +- `category`: The data category for which the discard reason applies. These are the same data categories used for [rate limits](/sdk/endpoints/rate-limiting/#definitions). - `quantity`: The number of events which were lost The following discard reasons are currently defined for `discarded_events`: diff --git a/src/docs/sdk/envelopes.mdx b/src/docs/sdk/protocol/envelopes.mdx similarity index 98% rename from src/docs/sdk/envelopes.mdx rename to src/docs/sdk/protocol/envelopes.mdx index 0e816c83c8..2403742cc5 100644 --- a/src/docs/sdk/envelopes.mdx +++ b/src/docs/sdk/protocol/envelopes.mdx @@ -1,6 +1,6 @@ --- title: Envelopes -sidebar_order: 7 +sidebar_order: 10 --- This document defines the Envelope and Item formats used by Sentry for data @@ -125,7 +125,7 @@ Envelopes can have a number of headers which are valid in all situations: `sdk` -: *Object, recommended.* This can carry the same payload as the `sdk` interface +: *Object, recommended.* This can carry the same payload as the `sdk` interface in the event payload but can be carried for all events. This means that SDK information can be carried for minidumps, session data and other submissions. @@ -302,7 +302,7 @@ Each Envelope consists of headers and a potentially empty list of Items, each with their own headers. Which Headers are required depends on the Items in an Envelope. This section describes all Item types and their respective required headers. It is worth noting that the list of Item types doesn't match the data -categories used for [rate limiting](/sdk/rate-limiting/#definitions) and +categories used for [rate limiting](/sdk/endpoints/rate-limiting/#definitions) and client reports. The type of an Item is declared in the `type` header, as well as the payload @@ -413,7 +413,7 @@ file. It is always associated to an event or transaction. Item type `"session"` contains a single session initialization or update to an existing session for Release Health. -See the sessions documentation for the payload +See the sessions documentation for the payload details. **Constraints:** @@ -429,7 +429,7 @@ details. Item type `"sessions"` contains buckets of pre-aggregated session counts. -See the sessions documentation for the payload +See the sessions documentation for the payload details. **Constraints:** diff --git a/src/docs/sdk/event-payloads/breadcrumbs.mdx b/src/docs/sdk/protocol/event-payloads/breadcrumbs.mdx similarity index 100% rename from src/docs/sdk/event-payloads/breadcrumbs.mdx rename to src/docs/sdk/protocol/event-payloads/breadcrumbs.mdx diff --git a/src/docs/sdk/event-payloads/contexts.mdx b/src/docs/sdk/protocol/event-payloads/contexts.mdx similarity index 98% rename from src/docs/sdk/event-payloads/contexts.mdx rename to src/docs/sdk/protocol/event-payloads/contexts.mdx index ad067d7290..51940ef406 100644 --- a/src/docs/sdk/event-payloads/contexts.mdx +++ b/src/docs/sdk/protocol/event-payloads/contexts.mdx @@ -215,7 +215,7 @@ confusion about which OS context represents what. So here's some examples: the SDK (if at all). Additionally, the Sentry server will attempt to parse the `User-Agent` header - from the event's [Request Interface](/sdk/event-payloads/request/) and create a _secondary_ OS + from the event's [Request Interface](/sdk/protocol/event-payloads/request/) and create a _secondary_ OS context under the non-default key `"client_os"`. - In events reported from a JS web frontend, the SDK typically reports no OS @@ -607,7 +607,7 @@ The `type` and default key is `"cloud_resource"`. ### Example Cloud Resource Context -The following example illustrates the contexts part of the event payload and omits other attributes for simplicity. +The following example illustrates the contexts part of the event payload and omits other attributes for simplicity. ```json { @@ -649,7 +649,7 @@ Additional information that allows Sentry to connect multiple transactions, span `op` -: _Optional_. Short code identifying the type of operation the span is measuring. For more details, see [Sentry's conventions around span operations](https://develop.sentry.dev/sdk/performance/span-operations/). +: _Optional_. Short code identifying the type of operation the span is measuring. For more details, see [Sentry's conventions around span operations](/sdk/telemetry/tracing/span-operations/). - Example: `"http.server"` @@ -701,13 +701,13 @@ Additional information that allows Sentry to connect multiple transactions, span `dynamic_sampling_context` -: _Optional_. The [Dynamic Sampling Context](https://develop.sentry.dev/sdk/performance/dynamic-sampling-context/). +: _Optional_. The [Dynamic Sampling Context](/sdk/telemetry/tracing/dynamic-sampling-context/). - Example: `{ "trace_id": "12312012123120121231201212312012", "sample_rate": "1.0", "public_key": "93D0D1125146288EAEE2A9B3AF4F96CCBE3CB316" },` `origin` -: _Optional_. The origin of the trace indicates what created the trace. For more details, see trace origin. +: _Optional_. The origin of the trace indicates what created the trace. For more details, see trace origin. `data` diff --git a/src/docs/sdk/event-payloads/debugmeta.mdx b/src/docs/sdk/protocol/event-payloads/debugmeta.mdx similarity index 99% rename from src/docs/sdk/event-payloads/debugmeta.mdx rename to src/docs/sdk/protocol/event-payloads/debugmeta.mdx index b322d0cf98..637e5c4b63 100644 --- a/src/docs/sdk/event-payloads/debugmeta.mdx +++ b/src/docs/sdk/protocol/event-payloads/debugmeta.mdx @@ -29,7 +29,7 @@ system symbols, and is not required for other SDKs. ## Debug Images The list of debug images contains all dynamic libraries loaded into the process -and their memory addresses. Instruction addresses in the [Stack Trace](/sdk/event-payloads/stacktrace/) are +and their memory addresses. Instruction addresses in the [Stack Trace](/sdk/protocol/event-payloads/stacktrace/) are mapped into the list of debug images in order to retrieve debug files for symbolication. diff --git a/src/docs/sdk/event-payloads/exception.mdx b/src/docs/sdk/protocol/event-payloads/exception.mdx similarity index 95% rename from src/docs/sdk/event-payloads/exception.mdx rename to src/docs/sdk/protocol/event-payloads/exception.mdx index 7c924f350e..50044616ad 100644 --- a/src/docs/sdk/event-payloads/exception.mdx +++ b/src/docs/sdk/protocol/event-payloads/exception.mdx @@ -5,7 +5,7 @@ sidebar_order: 2 The Exception Interface specifies an exception or error that occurred in a program. -An event may contain one or more exceptions in an attribute named `exception`. +An event may contain one or more exceptions in an attribute named `exception`. The `exception` attribute should be an object with the attribute `values` containing a list of one or more values that are objects in the format described @@ -41,7 +41,7 @@ description of `ValueError`. `thread_id` -: An optional value which refers to a thread in the Threads Interface. +: An optional value which refers to a thread in the Threads Interface. `mechanism` @@ -50,7 +50,7 @@ created this exception. `stacktrace` -: An optional stack trace object corresponding to the Stack Trace Interface. +: An optional stack trace object corresponding to the Stack Trace Interface. ## Exception Mechanism @@ -210,7 +210,7 @@ information. ## Examples The following examples illustrate multiple ways to send exceptions. Each example -contains the exception part of the event payload and omits other +contains the exception part of the event payload and omits other attributes for simplicity. A single exception: diff --git a/src/docs/sdk/event-payloads/index.mdx b/src/docs/sdk/protocol/event-payloads/index.mdx similarity index 97% rename from src/docs/sdk/event-payloads/index.mdx rename to src/docs/sdk/protocol/event-payloads/index.mdx index 26c1538ce0..560323b237 100644 --- a/src/docs/sdk/event-payloads/index.mdx +++ b/src/docs/sdk/protocol/event-payloads/index.mdx @@ -1,11 +1,12 @@ --- title: Event Payloads +sidebar_order: 20 --- Events are the fundamental data that clients, often through the use of an SDK, send to the Sentry server. -Events are packed into [envelopes](/sdk/envelopes/) and are sent to the `/api/{PROJECT_ID}/envelope/` API endpoint. +Events are packed into [envelopes](/sdk/protocol/envelopes/) and are sent to the `/api/{PROJECT_ID}/envelope/` API endpoint. Sending event payloads to the `/api/{PROJECT_ID}/store/` API endpoint is deprecated. @@ -288,7 +289,7 @@ These limits are subject to future change and defined currently as: - *1MB* decompressed (and `200KB` compressed) for events of type `error` - *1MB* decompressed (and `200KB` compressed) for events of type `transaction` -Sessions, client reports, replays, check-ins, and profiles are not events and have different size limits. See [Envelope Size Limits](/sdk/envelopes/#size-limits). +Sessions, client reports, replays, check-ins, and profiles are not events and have different size limits. See [Envelope Size Limits](/sdk/protocol/envelopes/#size-limits). ## Core Interfaces diff --git a/src/docs/sdk/event-payloads/lockreason.mdx b/src/docs/sdk/protocol/event-payloads/lockreason.mdx similarity index 86% rename from src/docs/sdk/event-payloads/lockreason.mdx rename to src/docs/sdk/protocol/event-payloads/lockreason.mdx index 58768cd09b..b924b1bcd2 100644 --- a/src/docs/sdk/event-payloads/lockreason.mdx +++ b/src/docs/sdk/protocol/event-payloads/lockreason.mdx @@ -8,7 +8,7 @@ to determine which other thread is holding the lock in case the current thread i -Lock reasons are always part of a [thread](/sdk/event-payloads/threads/). They cannot be declared as a top-level event property. +Lock reasons are always part of a [thread](/sdk/protocol/event-payloads/threads/). They cannot be declared as a top-level event property. diff --git a/src/docs/sdk/event-payloads/message.mdx b/src/docs/sdk/protocol/event-payloads/message.mdx similarity index 100% rename from src/docs/sdk/event-payloads/message.mdx rename to src/docs/sdk/protocol/event-payloads/message.mdx diff --git a/src/docs/sdk/event-payloads/properties/contexts_trace.mdx b/src/docs/sdk/protocol/event-payloads/properties/contexts_trace.mdx similarity index 84% rename from src/docs/sdk/event-payloads/properties/contexts_trace.mdx rename to src/docs/sdk/protocol/event-payloads/properties/contexts_trace.mdx index 69cab72623..93e86a74f7 100644 --- a/src/docs/sdk/event-payloads/properties/contexts_trace.mdx +++ b/src/docs/sdk/protocol/event-payloads/properties/contexts_trace.mdx @@ -1,6 +1,6 @@ `contexts.trace` -: _Recommended_. A Transaction has to have a specific `contexts.trace` entry that contains tracing information. See the [Trace Context documentation](/sdk/event-payloads/contexts/#trace-context). +: _Recommended_. A Transaction has to have a specific `contexts.trace` entry that contains tracing information. See the [Trace Context documentation](/sdk/protocol/event-payloads/contexts/#trace-context). ```json { diff --git a/src/docs/sdk/event-payloads/properties/description.mdx b/src/docs/sdk/protocol/event-payloads/properties/description.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/description.mdx rename to src/docs/sdk/protocol/event-payloads/properties/description.mdx diff --git a/src/docs/sdk/event-payloads/properties/event_id.mdx b/src/docs/sdk/protocol/event-payloads/properties/event_id.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/event_id.mdx rename to src/docs/sdk/protocol/event-payloads/properties/event_id.mdx diff --git a/src/docs/sdk/event-payloads/properties/measurements.mdx b/src/docs/sdk/protocol/event-payloads/properties/measurements.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/measurements.mdx rename to src/docs/sdk/protocol/event-payloads/properties/measurements.mdx diff --git a/src/docs/sdk/event-payloads/properties/op.mdx b/src/docs/sdk/protocol/event-payloads/properties/op.mdx similarity index 52% rename from src/docs/sdk/event-payloads/properties/op.mdx rename to src/docs/sdk/protocol/event-payloads/properties/op.mdx index 3fc0aca482..eb5e704e86 100644 --- a/src/docs/sdk/event-payloads/properties/op.mdx +++ b/src/docs/sdk/protocol/event-payloads/properties/op.mdx @@ -2,7 +2,7 @@ : _Recommended_. Short code identifying the type of operation the span is measuring. -For more details, see Sentry's conventions around span operations. +For more details, see Sentry's conventions around span operations. ```json { diff --git a/src/docs/sdk/event-payloads/properties/parent_span_id.mdx b/src/docs/sdk/protocol/event-payloads/properties/parent_span_id.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/parent_span_id.mdx rename to src/docs/sdk/protocol/event-payloads/properties/parent_span_id.mdx diff --git a/src/docs/sdk/event-payloads/properties/span_id.mdx b/src/docs/sdk/protocol/event-payloads/properties/span_id.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/span_id.mdx rename to src/docs/sdk/protocol/event-payloads/properties/span_id.mdx diff --git a/src/docs/sdk/event-payloads/properties/span_start_timestamp.mdx b/src/docs/sdk/protocol/event-payloads/properties/span_start_timestamp.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/span_start_timestamp.mdx rename to src/docs/sdk/protocol/event-payloads/properties/span_start_timestamp.mdx diff --git a/src/docs/sdk/event-payloads/properties/span_timestamp.mdx b/src/docs/sdk/protocol/event-payloads/properties/span_timestamp.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/span_timestamp.mdx rename to src/docs/sdk/protocol/event-payloads/properties/span_timestamp.mdx diff --git a/src/docs/sdk/event-payloads/properties/spans.mdx b/src/docs/sdk/protocol/event-payloads/properties/spans.mdx similarity index 92% rename from src/docs/sdk/event-payloads/properties/spans.mdx rename to src/docs/sdk/protocol/event-payloads/properties/spans.mdx index ea83d55fc6..ee1b7187e6 100644 --- a/src/docs/sdk/event-payloads/properties/spans.mdx +++ b/src/docs/sdk/protocol/event-payloads/properties/spans.mdx @@ -1,6 +1,6 @@ `spans` -: _Recommended_. A list of [Spans](/sdk/event-payloads/span/). +: _Recommended_. A list of [Spans](/sdk/protocol/event-payloads/span/). ```json { diff --git a/src/docs/sdk/event-payloads/properties/status.mdx b/src/docs/sdk/protocol/event-payloads/properties/status.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/status.mdx rename to src/docs/sdk/protocol/event-payloads/properties/status.mdx diff --git a/src/docs/sdk/event-payloads/properties/tags.mdx b/src/docs/sdk/protocol/event-payloads/properties/tags.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/tags.mdx rename to src/docs/sdk/protocol/event-payloads/properties/tags.mdx diff --git a/src/docs/sdk/event-payloads/properties/trace_id.mdx b/src/docs/sdk/protocol/event-payloads/properties/trace_id.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/trace_id.mdx rename to src/docs/sdk/protocol/event-payloads/properties/trace_id.mdx diff --git a/src/docs/sdk/event-payloads/properties/transaction_info.mdx b/src/docs/sdk/protocol/event-payloads/properties/transaction_info.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/transaction_info.mdx rename to src/docs/sdk/protocol/event-payloads/properties/transaction_info.mdx diff --git a/src/docs/sdk/event-payloads/properties/type.mdx b/src/docs/sdk/protocol/event-payloads/properties/type.mdx similarity index 100% rename from src/docs/sdk/event-payloads/properties/type.mdx rename to src/docs/sdk/protocol/event-payloads/properties/type.mdx diff --git a/src/docs/sdk/event-payloads/request.mdx b/src/docs/sdk/protocol/event-payloads/request.mdx similarity index 100% rename from src/docs/sdk/event-payloads/request.mdx rename to src/docs/sdk/protocol/event-payloads/request.mdx diff --git a/src/docs/sdk/event-payloads/sdk.mdx b/src/docs/sdk/protocol/event-payloads/sdk.mdx similarity index 98% rename from src/docs/sdk/event-payloads/sdk.mdx rename to src/docs/sdk/protocol/event-payloads/sdk.mdx index 8957abf377..294e52b7ee 100644 --- a/src/docs/sdk/event-payloads/sdk.mdx +++ b/src/docs/sdk/protocol/event-payloads/sdk.mdx @@ -71,7 +71,7 @@ reference (branch, tag or SHA). ## Example -The following example illustrates the SDK part of the event payload and omits other +The following example illustrates the SDK part of the event payload and omits other attributes for simplicity. ```json diff --git a/src/docs/sdk/event-payloads/span.mdx b/src/docs/sdk/protocol/event-payloads/span.mdx similarity index 79% rename from src/docs/sdk/event-payloads/span.mdx rename to src/docs/sdk/protocol/event-payloads/span.mdx index 15cf247a38..3db881de71 100644 --- a/src/docs/sdk/event-payloads/span.mdx +++ b/src/docs/sdk/protocol/event-payloads/span.mdx @@ -4,7 +4,7 @@ title: Span Interface The Span Interface specifies a series of _timed_ application events that have a start and end time. -A [Transaction](/sdk/event-payloads/transaction/) may contain zero or more Spans in an array attribute named `spans`. Spans in the list don't have to be ordered, they will be ordered by start / end time on the Server. +A [Transaction](/sdk/protocol/event-payloads/transaction/) may contain zero or more Spans in an array attribute named `spans`. Spans in the list don't have to be ordered, they will be ordered by start / end time on the Server. While Span attributes will be normalized on the server, a Span is most useful when it includes at least an `op` and `description`. @@ -32,7 +32,7 @@ import "./properties/tags.mdx"; : _Optional_. Arbitrary data associated with this Span. -The semantic conventions for the `data` field are described in Sentry's Span Convention Documentation. +The semantic conventions for the `data` field are described in Sentry's Span Convention Documentation. ```json { @@ -47,11 +47,11 @@ The semantic conventions for the `data` field are described in trace origin. +: _Optional_. The origin of the span indicates what created the span. For more details, see trace origin. ## Examples -The following example illustrates the Span as part of the [Transaction](/sdk/event-payloads/transaction/) and omits other attributes for simplicity. +The following example illustrates the Span as part of the [Transaction](/sdk/protocol/event-payloads/transaction/) and omits other attributes for simplicity. ```json { diff --git a/src/docs/sdk/event-payloads/stacktrace.mdx b/src/docs/sdk/protocol/event-payloads/stacktrace.mdx similarity index 96% rename from src/docs/sdk/event-payloads/stacktrace.mdx rename to src/docs/sdk/protocol/event-payloads/stacktrace.mdx index e37956f84d..d4b6e6082e 100644 --- a/src/docs/sdk/event-payloads/stacktrace.mdx +++ b/src/docs/sdk/protocol/event-payloads/stacktrace.mdx @@ -13,8 +13,8 @@ Stack traces are always part of an exception or a thread. They cannot be declared as a top-level event property. When adding a stack trace to an event, follow this rule of thumb: -- If the stack trace is part of an error, exception or crash, add it to the [Exception Interface](/sdk/event-payloads/exception/). -- Otherwise, add it as a thread in the [Threads Interface](/sdk/event-payloads/threads/). +- If the stack trace is part of an error, exception or crash, add it to the [Exception Interface](/sdk/protocol/event-payloads/exception/). +- Otherwise, add it as a thread in the [Threads Interface](/sdk/protocol/event-payloads/threads/). @@ -121,7 +121,7 @@ The following attributes are primarily used for C-based languages: : An optional instruction address for symbolication. This should be a string with a hexadecimal number that includes a `0x` prefix. If this is set and a -known image is defined in the [Debug Meta Interface](/sdk/event-payloads/debugmeta/), then +known image is defined in the [Debug Meta Interface](/sdk/protocol/event-payloads/debugmeta/), then symbolication can take place. Note that the `addr_mode` attribute can control the behavior of this address. diff --git a/src/docs/sdk/event-payloads/template.mdx b/src/docs/sdk/protocol/event-payloads/template.mdx similarity index 100% rename from src/docs/sdk/event-payloads/template.mdx rename to src/docs/sdk/protocol/event-payloads/template.mdx diff --git a/src/docs/sdk/event-payloads/threads.mdx b/src/docs/sdk/protocol/event-payloads/threads.mdx similarity index 85% rename from src/docs/sdk/event-payloads/threads.mdx rename to src/docs/sdk/protocol/event-payloads/threads.mdx index d3e0a7f63a..d7ab99c670 100644 --- a/src/docs/sdk/event-payloads/threads.mdx +++ b/src/docs/sdk/protocol/event-payloads/threads.mdx @@ -6,13 +6,13 @@ sidebar_order: 10 The Threads Interface specifies threads that were running at the time an event happened. These threads can also contain stack traces. -An [event](/sdk/event-payloads/) may contain one or more threads in an attribute named `threads`. +An [event](/sdk/protocol/event-payloads/) may contain one or more threads in an attribute named `threads`. The `threads` attribute should be an object with the attribute `values` containing one or more values that are objects in the format described below. Alternatively, the `threads` attribute may be a flat list of objects in the format below. -As per Sentry policy, the thread that crashed with an [exception](/sdk/event-payloads/exception/) should not +As per Sentry policy, the thread that crashed with an [exception](/sdk/protocol/event-payloads/exception/) should not have a stack trace, but instead, the `thread_id` attribute should be set on the exception and Sentry will connect the two. @@ -50,20 +50,20 @@ On mobile platforms this is oftentimes referred to as the "main thread" or "ui t `held_locks` : _Optional_. Represents a collection of locks (monitor objects) held by a thread. A dictionary of lock object memory addresses and -their respective lock reason/details. Lock reason corresponds to the [Lock Reason Interface](/sdk/event-payloads/lockreason/). +their respective lock reason/details. Lock reason corresponds to the [Lock Reason Interface](/sdk/protocol/event-payloads/lockreason/). `stacktrace` -: _Optional_. A stack trace object corresponding to the [Stack Trace Interface](/sdk/event-payloads/stacktrace/). +: _Optional_. A stack trace object corresponding to the [Stack Trace Interface](/sdk/protocol/event-payloads/stacktrace/). If this is an error event, the stack trace of the main exception should be -declared in the [Exception Interface](/sdk/event-payloads/exception/) instead. +declared in the [Exception Interface](/sdk/protocol/event-payloads/exception/) instead. Sentry will automatically move the stack trace of the only crashed thread, if there is a single exception. ## Examples -The following example illustrates the threads part of the [event payload](/sdk/event-payloads/) and omits +The following example illustrates the threads part of the [event payload](/sdk/protocol/event-payloads/) and omits other attributes for simplicity. ```json diff --git a/src/docs/sdk/event-payloads/transaction.mdx b/src/docs/sdk/protocol/event-payloads/transaction.mdx similarity index 58% rename from src/docs/sdk/event-payloads/transaction.mdx rename to src/docs/sdk/protocol/event-payloads/transaction.mdx index db3d1a8d8c..67c8979269 100644 --- a/src/docs/sdk/event-payloads/transaction.mdx +++ b/src/docs/sdk/protocol/event-payloads/transaction.mdx @@ -4,24 +4,32 @@ title: Transaction Payloads Transactions are used to send tracing events to Sentry. -Transactions must be wrapped in an [Envelope](/sdk/envelopes/) and therefore also be sent to the Envelope endpoint. +Transactions must be wrapped in an [Envelope](/sdk/protocol/envelopes/) and therefore also be sent to the Envelope endpoint. Envelopes are a new format and therefore only work on Sentry >= 10. More - information can be found on the Envelope page. + information can be found on the Envelope page. ## Anatomy -A Transaction is basically a [Span](/sdk/event-payloads/span/) combined with an [Event](/sdk/event-payloads/). When using +A Transaction is basically a [Span](/sdk/protocol/event-payloads/span/) combined with an [Event](/sdk/protocol/event-payloads/). When using tracing with our SDKs you usually create a Span tree, the root node and therefore the whole tree is considered to be the Transaction. -So technically a Transaction is just a Span. A Transaction must also have a `contexts.trace` (which contains some data of the [Span](/sdk/event-payloads/span/)) and some other +So technically a Transaction is just a Span. A Transaction must also have a `contexts.trace` (which contains some data of the [Span](/sdk/protocol/event-payloads/span/)) and some other properties that will be covered in the next section. -Transactions are [Events](/sdk/event-payloads/) enriched with [Span](/sdk/event-payloads/span/) data. +Transactions are [Events](/sdk/protocol/event-payloads/) enriched with [Span](/sdk/protocol/event-payloads/span/) data. We are only going to list here what is important for a Transaction. -import "./properties/type.mdx"; +`type` + +: _Required_. A Transaction has to have this value set to `transaction`. + + ```json + { + "type": "transaction" + } + ``` import "./properties/span_start_timestamp.mdx"; diff --git a/src/docs/sdk/event-payloads/types.mdx b/src/docs/sdk/protocol/event-payloads/types.mdx similarity index 86% rename from src/docs/sdk/event-payloads/types.mdx rename to src/docs/sdk/protocol/event-payloads/types.mdx index 6af08239b3..17232c16f1 100644 --- a/src/docs/sdk/event-payloads/types.mdx +++ b/src/docs/sdk/protocol/event-payloads/types.mdx @@ -3,7 +3,7 @@ title: Event Type Definitions --- This page documents the event schema for errors, just like the other documents -at Event Payloads do. However, the +at Event Payloads do. However, the sections here are automatically generated from code, and because of that they are more complete and less out of date. We intend to make this page the single source of truth and replace all the other "interface" pages, but there is still diff --git a/src/docs/sdk/event-payloads/user.mdx b/src/docs/sdk/protocol/event-payloads/user.mdx similarity index 95% rename from src/docs/sdk/event-payloads/user.mdx rename to src/docs/sdk/protocol/event-payloads/user.mdx index 14d2c1cde2..2301131cbf 100644 --- a/src/docs/sdk/event-payloads/user.mdx +++ b/src/docs/sdk/protocol/event-payloads/user.mdx @@ -57,7 +57,7 @@ Approximate geographical location of the end user or device. SDKs running on client platforms, such as browsers and mobile applications, should set `ip_address = "{{auto}}"` by default. Server-side SDKs should -populate the [Request Interface](/sdk/event-payloads/request/), instead. Sentry +populate the [Request Interface](/sdk/protocol/event-payloads/request/), instead. Sentry employs several fallbacks to backfill the IP address: 1. Use `user.ip_address`, if set directly. diff --git a/src/docs/sdk/protocol/index.mdx b/src/docs/sdk/protocol/index.mdx new file mode 100644 index 0000000000..a554e16743 --- /dev/null +++ b/src/docs/sdk/protocol/index.mdx @@ -0,0 +1,5 @@ +--- +title: Protocol +--- + + \ No newline at end of file diff --git a/src/docs/sdk/sessions.mdx b/src/docs/sdk/protocol/sessions.mdx similarity index 99% rename from src/docs/sdk/sessions.mdx rename to src/docs/sdk/protocol/sessions.mdx index cd323c4da5..f45abf6203 100644 --- a/src/docs/sdk/sessions.mdx +++ b/src/docs/sdk/protocol/sessions.mdx @@ -1,6 +1,6 @@ --- title: Sessions -sidebar_order: 12 +sidebar_order: 100 --- @@ -9,7 +9,7 @@ Looking for Sentry's **Session Replay**? Click envelopes +For basic health tracking Sentry accepts envelopes containing session update events. These session update events can be used to inform Sentry about release and project associated project health. @@ -378,7 +378,7 @@ received and end it when a response is returned. ### Unified API Implications -The Unified API that SDKs should +The Unified API that SDKs should adhere to defines the concepts of `Hub`, `Scope` and `Client`. Conceptually speaking, the session is a concern of the `Hub`, and unlike scopes, diff --git a/src/docs/sdk/check-ins.mdx b/src/docs/sdk/telemetry/check-ins/index.mdx similarity index 96% rename from src/docs/sdk/check-ins.mdx rename to src/docs/sdk/telemetry/check-ins/index.mdx index f421ca8952..fbb83ae3b8 100644 --- a/src/docs/sdk/check-ins.mdx +++ b/src/docs/sdk/telemetry/check-ins/index.mdx @@ -1,6 +1,6 @@ --- title: Check-Ins -sidebar_order: 20 +sidebar_order: 50 --- ## Cron Monitor Check-In Payload @@ -66,7 +66,7 @@ The following fields exist: `contexts` : _Object, optional_. A dictionary of contextual information about the environment running - the check-in. Right now we only support the [trace context](https://develop.sentry.dev/sdk/event-payloads/contexts/#trace-context) + the check-in. Right now we only support the [trace context](/sdk/protocol/event-payloads/contexts/#trace-context) and use the `trace_id` in order to link check-ins to associated errors. ## Monitor upsert support diff --git a/src/docs/sdk/telemetry/index.mdx b/src/docs/sdk/telemetry/index.mdx new file mode 100644 index 0000000000..b3f31e2e60 --- /dev/null +++ b/src/docs/sdk/telemetry/index.mdx @@ -0,0 +1,5 @@ +--- +title: Telemetry +--- + + \ No newline at end of file diff --git a/src/docs/sdk/metrics.mdx b/src/docs/sdk/telemetry/metrics/index.mdx similarity index 98% rename from src/docs/sdk/metrics.mdx rename to src/docs/sdk/telemetry/metrics/index.mdx index ae145e8873..531f62f804 100644 --- a/src/docs/sdk/metrics.mdx +++ b/src/docs/sdk/telemetry/metrics/index.mdx @@ -1,6 +1,6 @@ --- title: Metrics -sidebar_order: 13 +sidebar_order: 30 --- Sentry supports the emission of pre-aggregated metrics information via the `statsd` @@ -344,7 +344,7 @@ sentry_sdk.init( Additionally SDKs are encouraged to capture location information once per metric. At metric emission time the system shall be collecting which code location emitted a metric and retain it. -For that the same format as for the [`frame`](/sdk/event-payloads/stacktrace/) on the stacktrace +For that the same format as for the [`frame`](/sdk/protocol/event-payloads/stacktrace/) on the stacktrace shall be used. `stacklevel` number of frames shall be ignored. The meta data is emitted in JSON as envelope item called `metric_meta`: @@ -363,7 +363,7 @@ The meta data is emitted in JSON as envelope item called `metric_meta`: Today only code mappings are supported. Each key is an encoded MRI (eg: `c:custom/foo@none`), each value in the mapping array has a key called `type` which today can only be `"location"`. All other -keys are the same format as the [`frame`](/sdk/event-payloads/stacktrace/) on the stacktrace. Today +keys are the same format as the [`frame`](/sdk/protocol/event-payloads/stacktrace/) on the stacktrace. Today SDKs should send code locations at least once a day, and they can round the timestamp. ## Reference Implementation diff --git a/src/docs/sdk/profiles.mdx b/src/docs/sdk/telemetry/profiles/index.mdx similarity index 97% rename from src/docs/sdk/profiles.mdx rename to src/docs/sdk/telemetry/profiles/index.mdx index f7aa5d2118..36a4f962f1 100644 --- a/src/docs/sdk/profiles.mdx +++ b/src/docs/sdk/telemetry/profiles/index.mdx @@ -90,7 +90,7 @@ in the same envelope as the associated transaction. `debug_meta` : *Object, required on native platforms.* This carry the same payload as `debug_meta` interface. It is required to +to="/sdk/protocol/event-payloads/sdk/">`debug_meta` interface. It is required to have it for native platforms in order to symbolicate, otherwise you can omit it. `device` @@ -342,7 +342,7 @@ the same `stack_id` for each sample that needs it. `frames` : *List, required*. Contains a list of frame objects (see [Frame -Attributes](/sdk/event-payloads/stacktrace/#frame-attributes)). +Attributes](/sdk/protocol/event-payloads/stacktrace/#frame-attributes)). Each object should contain at least a `filename`, `function` or `instruction_addr` attribute. All values are optional, but recommended. @@ -405,8 +405,8 @@ It's suggested to remove unnecessary data like thread data without samples from ## Ingestion After this payload is generated, serialize it as JSON, pack it into the same -[Envelope](/sdk/envelopes/) as the associated transaction with the item type -[`profile`](/sdk/envelopes/#profile) and send it to Relay. +[Envelope](/sdk/protocol/envelopes/) as the associated transaction with the item type +[`profile`](/sdk/protocol/envelopes/#profile) and send it to Relay. This envelope should look like this: diff --git a/src/docs/sdk/performance/backpressure.mdx b/src/docs/sdk/telemetry/tracing/backpressure.mdx similarity index 98% rename from src/docs/sdk/performance/backpressure.mdx rename to src/docs/sdk/telemetry/tracing/backpressure.mdx index ee4a3852d4..07c20f9b5e 100644 --- a/src/docs/sdk/performance/backpressure.mdx +++ b/src/docs/sdk/telemetry/tracing/backpressure.mdx @@ -7,7 +7,7 @@ Backend SDKs that are typically used in server environments are expected to impl This component will periodically introspect the SDK for measures of throughput and if too high, will dynamically downsample transactions by halving the sample rate temporarily. Once the system has recovered to a healthy state, the SDK will revert to the sample rate set by the user. -![Backpressure](backpressure.png) +![Backpressure](./backpressure.png) ## Configuration diff --git a/src/docs/sdk/performance/backpressure.png b/src/docs/sdk/telemetry/tracing/backpressure.png similarity index 100% rename from src/docs/sdk/performance/backpressure.png rename to src/docs/sdk/telemetry/tracing/backpressure.png diff --git a/src/docs/sdk/performance/dynamic-sampling-context.mdx b/src/docs/sdk/telemetry/tracing/dynamic-sampling-context.mdx similarity index 97% rename from src/docs/sdk/performance/dynamic-sampling-context.mdx rename to src/docs/sdk/telemetry/tracing/dynamic-sampling-context.mdx index 204de4936d..4872283624 100644 --- a/src/docs/sdk/performance/dynamic-sampling-context.mdx +++ b/src/docs/sdk/telemetry/tracing/dynamic-sampling-context.mdx @@ -2,7 +2,7 @@ title: 'Dynamic Sampling Context (DSC)' --- -All data sent to Sentry will end up in a [Trace](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/#traces-transactions-and-spans). Traces can be sampled by the `tracesSampleRate` or `tracesSampler` options in the SDKs. +All data sent to Sentry will end up in a [Trace](https://docs.sentry.io/concepts/key-terms/tracing/distributed-tracing/#traces-transactions-and-spans). Traces can be sampled by the `tracesSampleRate` or `tracesSampler` options in the SDKs. Changing those options has quite a few consequences for users of Sentry SDKs: @@ -89,7 +89,7 @@ For that reason: **Only if a transaction name has good quality, it should be inc - `"/organization/:organizationId/user/:userId"` - `"UserListUIComponent"` -SDKs can leverage transaction annotations (in particular the `source` of the transaction name) to determine which transaction names have a good quality. +SDKs can leverage transaction annotations (in particular the `source` of the transaction name) to determine which transaction names have a good quality.     @@ -114,7 +114,7 @@ For the propagation of DSC, SDKs first read the DSC from the `baggage` header of To propagate DSC to downstream SDKs/services, we create a `baggage` header (or modify an existing one) through HTTP request instrumentation. -The `baggage` header should only be attached to an outgoing request if the request's URL matches at least one entry of the [`tracePropagationTargets`](/sdk/performance/#tracepropagationtargets) SDK option or this option is set to `null` or not set. +The `baggage` header should only be attached to an outgoing request if the request's URL matches at least one entry of the [`tracePropagationTargets`](/sdk/telemetry/tracing/#tracepropagationtargets) SDK option or this option is set to `null` or not set. SDKs must set all of the keys in the form of "`sentry-[name]`". Where `[name]` is the attribute in the [DSC Specification](#dsc-specification). The prefix "`sentry-`" acts to identify key-value pairs set by Sentry SDKs. diff --git a/src/docs/sdk/performance/frames-delay.mdx b/src/docs/sdk/telemetry/tracing/frames-delay.mdx similarity index 98% rename from src/docs/sdk/performance/frames-delay.mdx rename to src/docs/sdk/telemetry/tracing/frames-delay.mdx index aadb9f536a..cca503f3ac 100644 --- a/src/docs/sdk/performance/frames-delay.mdx +++ b/src/docs/sdk/telemetry/tracing/frames-delay.mdx @@ -55,7 +55,7 @@ When a frame takes 20 ms to render, the frame delay is `20ms - 16.67ms = 3.33ms change at any time, SDKs must check the expected frame rate for every frame. The frame delay for a span is the sum of frame delays for all slow and frozen frames during the start and end time of the span. -SDKs should attach frames delay in seconds to spans via span data +SDKs should attach frames delay in seconds to spans via span data and __attach frames delay to all spans__, regardless of on which thread a span runs, and as well to concurrently running spans. For transactions SDKs should send frames delay via the root span with span data. While it makes sense to calculate frames delay in milliseconds, __SDKs must send frames delay in seconds__, as SDKs already diff --git a/src/docs/sdk/performance/index.mdx b/src/docs/sdk/telemetry/tracing/index.mdx similarity index 95% rename from src/docs/sdk/performance/index.mdx rename to src/docs/sdk/telemetry/tracing/index.mdx index d5c65696d8..17d008df06 100644 --- a/src/docs/sdk/performance/index.mdx +++ b/src/docs/sdk/telemetry/tracing/index.mdx @@ -1,5 +1,5 @@ --- -title: "Guidelines for Performance Monitoring" +title: Tracing --- This document covers how SDKs should add support for Performance Monitoring with [Distributed @@ -26,7 +26,7 @@ This option shall enable the generation of transactions and propagation of trace ### `tracesSampleRate` -This should be a float/double between `0.0` and `1.0` (inclusive) and represents the percentage chance that any given transaction will be sent to Sentry. So, barring [outside influence](https://develop.sentry.dev/sdk/performance/#sampling), `0.0` is a 0% chance (none will be sent) and `1.0` is a 100% chance (all will be sent). This rate applies equally to all transactions; in other words, each transaction should have the same random chance of ending up with `sampled = true`, equal to the `tracesSampleRate`. +This should be a float/double between `0.0` and `1.0` (inclusive) and represents the percentage chance that any given transaction will be sent to Sentry. So, barring [outside influence](/sdk/telemetry/tracing/#sampling), `0.0` is a 0% chance (none will be sent) and `1.0` is a 100% chance (all will be sent). This rate applies equally to all transactions; in other words, each transaction should have the same random chance of ending up with `sampled = true`, equal to the `tracesSampleRate`. See more about how sampling should be performed below. @@ -46,7 +46,7 @@ This option takes an array of strings and/or regular expressions. SDKs should on SDKs may choose a default value which makes sense for their use case. Most SDKs default to the regex `.*` (meaning they attach headers to all outgoing requests), but deviation is allowed if necessary. For example, because of CORS, browser-based SDKs default to only adding headers to domain-internal requests. -See [`sentry-trace`](#header-sentry-trace), [`traceparent`](#header-traceparent) and [`baggage`](/sdk/performance/dynamic-sampling-context/#baggage-header) for more details on the individual headers which are attached to outgoing requests. +See [`sentry-trace`](#header-sentry-trace), [`traceparent`](#header-traceparent) and [`baggage`](/sdk/telemetry/tracing/dynamic-sampling-context/#baggage-header) for more details on the individual headers which are attached to outgoing requests. #### Example @@ -95,14 +95,14 @@ Over the wire, transactions are serialized to JSON as an augmented `Event`, and In the Sentry UI, you can use Discover to look at all events regardless of type, and the Issues and Performance sections to dive into errors and transactions, respectively. The [user-facing tracing documentation](https://docs.sentry.io/product/performance/distributed-tracing/#traces-transactions-and-spans) explains more of the concepts on the product level. -The [Span](/sdk/event-payloads/span/) class stores each individual span in a +The [Span](/sdk/protocol/event-payloads/span/) class stores each individual span in a trace. -The [Transaction](/sdk/event-payloads/transaction/) class is like a span, with a +The [Transaction](/sdk/protocol/event-payloads/transaction/) class is like a span, with a few key differences: - Transactions have `name`, spans don't. -- Transactions must specify the [source](/sdk/event-payloads/transaction/#transaction-annotations) of its `name` to indicate how the transaction name was generated. +- Transactions must specify the [source](/sdk/protocol/event-payloads/transaction/#transaction-annotations) of its `name` to indicate how the transaction name was generated. - Calling the `finish` method on spans record the span's end timestamp. For transactions, the `finish` method additionally sends an event to Sentry. @@ -140,7 +140,7 @@ tree as well as the unit of reporting to Sentry. - `super.finish()` (call finish on Span) - Send it to Sentry only if `sampled == true` - Like spans, can be given an optional `endTimestamp` value that should be passed into the `span.finish()` call - - A `Transaction` needs to be wrapped in an `Envelope` and sent to the [Envelope Endpoint](/sdk/envelopes/) + - A `Transaction` needs to be wrapped in an `Envelope` and sent to the [Envelope Endpoint](/sdk/protocol/envelopes/) - The `Transport` should use the same internal queue for `Transactions` / `Events` - The `Transport` should implement category-based rate limiting → - The `Transport` should deal with wrapping a `Transaction` in an `Envelope` internally @@ -188,7 +188,7 @@ A transaction's sampling decision should be passed to all of its children, inclu ### Backpressure -If the SDK supports backpressure handling, the overall sampling rate needs to be divided by the `downsamplingFactor` from the backpressure monitor. See [the backpressure spec](/sdk/performance/backpressure/#downsampling) for more details. +If the SDK supports backpressure handling, the overall sampling rate needs to be divided by the `downsamplingFactor` from the backpressure monitor. See [the backpressure spec](/sdk/telemetry/tracing/backpressure/#downsampling) for more details. ## Header `sentry-trace` diff --git a/src/docs/sdk/performance/modules/app-starts.mdx b/src/docs/sdk/telemetry/tracing/modules/app-starts.mdx similarity index 100% rename from src/docs/sdk/performance/modules/app-starts.mdx rename to src/docs/sdk/telemetry/tracing/modules/app-starts.mdx diff --git a/src/docs/sdk/performance/modules/assets.mdx b/src/docs/sdk/telemetry/tracing/modules/assets.mdx similarity index 100% rename from src/docs/sdk/performance/modules/assets.mdx rename to src/docs/sdk/telemetry/tracing/modules/assets.mdx diff --git a/src/docs/sdk/performance/modules/caches.mdx b/src/docs/sdk/telemetry/tracing/modules/caches.mdx similarity index 100% rename from src/docs/sdk/performance/modules/caches.mdx rename to src/docs/sdk/telemetry/tracing/modules/caches.mdx diff --git a/src/docs/sdk/telemetry/tracing/modules/index.mdx b/src/docs/sdk/telemetry/tracing/modules/index.mdx new file mode 100644 index 0000000000..8c5de0454b --- /dev/null +++ b/src/docs/sdk/telemetry/tracing/modules/index.mdx @@ -0,0 +1,15 @@ +--- +title: 'Insights Modules' +--- + +The list below contains SDK documentation for our various Insights Modules (formerly known as "Peformance Modules"). + +- [App Starts](/sdk/telemetry/tracing/modules/app-starts/) +- [Caches](/sdk/telemetry/tracing/modules/caches/) +- [LLM Monitoring](/sdk/telemetry/tracing/modules/llm-monitoring/) +- [Queues](/sdk/telemetry/tracing/modules/queues/) +- [Queries](/sdk/telemetry/tracing/modules/queries/) +- [Requests](/sdk/telemetry/tracing/modules/requests/) +- [Assets](/sdk/telemetry/tracing/modules/assets/) +- [Screen Loads](/sdk/telemetry/tracing/modules/screen-loads/) +- [Web Vitals](/sdk/telemetry/tracing/modules/web-vitals/) diff --git a/src/docs/sdk/performance/modules/llm-monitoring.mdx b/src/docs/sdk/telemetry/tracing/modules/llm-monitoring.mdx similarity index 100% rename from src/docs/sdk/performance/modules/llm-monitoring.mdx rename to src/docs/sdk/telemetry/tracing/modules/llm-monitoring.mdx diff --git a/src/docs/sdk/performance/modules/queries.mdx b/src/docs/sdk/telemetry/tracing/modules/queries.mdx similarity index 88% rename from src/docs/sdk/performance/modules/queries.mdx rename to src/docs/sdk/telemetry/tracing/modules/queries.mdx index eb97168f7f..2c4a550aa7 100644 --- a/src/docs/sdk/performance/modules/queries.mdx +++ b/src/docs/sdk/telemetry/tracing/modules/queries.mdx @@ -31,7 +31,7 @@ The `?` parameter is a placeholder in the query. The SDK must scrub out all valu ### Span Data -For full support, each database span should have a `data` attribute. `data` is itself a key-value lookup of attributes. Refer to [Database Span Data Conventions](/sdk/performance/span-data-conventions/#database) for a full list of attributes that database spans should have. We recommend that the SDK provide _all_ of those attributes for every span. However, the _minimal_ requirement is that the SDK provides the `db.system` attribute. +For full support, each database span should have a `data` attribute. `data` is itself a key-value lookup of attributes. Refer to [Database Span Data Conventions](/sdk/telemetry/tracing/span-data-conventions/#database) for a full list of attributes that database spans should have. We recommend that the SDK provide _all_ of those attributes for every span. However, the _minimal_ requirement is that the SDK provides the `db.system` attribute. ## Instrumentation Example diff --git a/src/docs/sdk/performance/modules/queues.mdx b/src/docs/sdk/telemetry/tracing/modules/queues.mdx similarity index 100% rename from src/docs/sdk/performance/modules/queues.mdx rename to src/docs/sdk/telemetry/tracing/modules/queues.mdx diff --git a/src/docs/sdk/performance/modules/requests.mdx b/src/docs/sdk/telemetry/tracing/modules/requests.mdx similarity index 95% rename from src/docs/sdk/performance/modules/requests.mdx rename to src/docs/sdk/telemetry/tracing/modules/requests.mdx index 99aa773f2a..ef652bf297 100644 --- a/src/docs/sdk/performance/modules/requests.mdx +++ b/src/docs/sdk/telemetry/tracing/modules/requests.mdx @@ -14,7 +14,7 @@ The SDK should auto-instrument all outgoing HTTP requests, regardless of the lib ### Span Data -None of the span data fields are hard requirements, but attaching as many of them as possible is a more future-proof approach. We recommend that the SDK adds every attribute listed in the [HTTP Span Data Conventions](/sdk/performance/span-data-conventions/#http). The minimal requirements are: +None of the span data fields are hard requirements, but attaching as many of them as possible is a more future-proof approach. We recommend that the SDK adds every attribute listed in the [HTTP Span Data Conventions](/sdk/telemetry/tracing/span-data-conventions/#http). The minimal requirements are: - `server.address` must be set to allow correct domain grouping _for descriptions containing relative URLs_. e.g., the description `"GET /data.json"` is missing a domain. In this case, `server.address` must be set. If the span description contains the full URL, `span.server` can be omitted - `http.response.status_code` must be set to enable response code breakdowns diff --git a/src/docs/sdk/performance/modules/screen-loads.mdx b/src/docs/sdk/telemetry/tracing/modules/screen-loads.mdx similarity index 100% rename from src/docs/sdk/performance/modules/screen-loads.mdx rename to src/docs/sdk/telemetry/tracing/modules/screen-loads.mdx diff --git a/src/docs/sdk/performance/modules/web-vitals.mdx b/src/docs/sdk/telemetry/tracing/modules/web-vitals.mdx similarity index 100% rename from src/docs/sdk/performance/modules/web-vitals.mdx rename to src/docs/sdk/telemetry/tracing/modules/web-vitals.mdx diff --git a/src/docs/sdk/performance/opentelemetry.mdx b/src/docs/sdk/telemetry/tracing/opentelemetry.mdx similarity index 98% rename from src/docs/sdk/performance/opentelemetry.mdx rename to src/docs/sdk/telemetry/tracing/opentelemetry.mdx index e0e8515249..b18d55f1d3 100644 --- a/src/docs/sdk/performance/opentelemetry.mdx +++ b/src/docs/sdk/telemetry/tracing/opentelemetry.mdx @@ -14,7 +14,7 @@ This document details Sentry's work in integrating and supporting [OpenTelemetry ## Background -When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our performance monitoring research document. +When Sentry performance monitoring was initially introduced, OpenTelemetry was in early stages. This lead to us adopt a slightly different model from OpenTelemetry, notably we have this concept of transactions that OpenTelemetry does not have. We've described this, and some more historical background, in our performance monitoring research document. ## Approach @@ -401,7 +401,7 @@ function generateSentryErrorsFromOtelSpan(otelSpan) { ## Span Protocol -Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](https://develop.sentry.dev/sdk/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). +Below describe the transformations between an OpenTelemetry span and a Sentry Span. Related: [the interface for a Sentry Span](/sdk/protocol/event-payloads/span/), [the Relay spec for a Sentry Span](https://github.com/getsentry/relay/blob/master/relay-general/src/protocol/span.rs) and the spec for an [OpenTelemetry span](https://github.com/open-telemetry/opentelemetry-proto/blob/724e427879e3d2bae2edc0218fff06e37b9eb46e/opentelemetry/proto/trace/v1/trace.proto#L80-L256). This is based on a mapping done as part of work on the [OpenTelemetry Sentry Exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/sentryexporter/docs/transformation.md). @@ -649,7 +649,7 @@ import {Span as OtelSpan} from '@opentelemetry/sdk-trace-base'; import {SemanticAttributes} from '@opentelemetry/semantic-conventions'; import {SpanStatusType as SentryStatus} from '@sentry/tracing'; -// canonicalCodesHTTPMap maps some HTTP codes to Sentry's span statuses. See possible mapping in https://develop.sentry.dev/sdk/event-payloads/span/ +// canonicalCodesHTTPMap maps some HTTP codes to Sentry's span statuses. See possible mapping in https://develop.sentry.dev/sdk/protocol/event-payloads/span/ const canonicalCodesHTTPMap: Record = { '400': 'failed_precondition', '401': 'unauthenticated', diff --git a/src/docs/sdk/research/performance/index.mdx b/src/docs/sdk/telemetry/tracing/research-performance-api.mdx similarity index 96% rename from src/docs/sdk/research/performance/index.mdx rename to src/docs/sdk/telemetry/tracing/research-performance-api.mdx index 5b3679f95b..8248ac2ec0 100644 --- a/src/docs/sdk/research/performance/index.mdx +++ b/src/docs/sdk/telemetry/tracing/research-performance-api.mdx @@ -14,7 +14,7 @@ After settling with an API, performance monitoring support was then expanded to Our initial implementation reused the mechanisms we had in place for error reporting: -- The [Event type](https://develop.sentry.dev/sdk/event-payloads/) was extended with new fields. That meant that instead of designing and implementing a whole new ingestion pipeline, we could save time and quickly start sending "events" to Sentry, this time, instead of errors, a new "transaction" event type. +- The [Event type](/sdk/protocol/event-payloads/) was extended with new fields. That meant that instead of designing and implementing a whole new ingestion pipeline, we could save time and quickly start sending "events" to Sentry, this time, instead of errors, a new "transaction" event type. - Since we were just sending a new type of event, the SDK transport layer was also reused. - And since we were sharing the ingestion pipeline, that meant we were sharing storage and the many parts of the processing that happens to all events. @@ -26,7 +26,7 @@ In the next section, we’ll discuss some of the shortcomings with the current m ## Identified Issues -While the reuse of the [Unified SDK architecture](https://develop.sentry.dev/sdk/unified-api/) (hubs, clients, scopes) and the transaction ingestion model have merits, experience revealed some issues that we categorize into two groups. +While the reuse of the [Unified SDK architecture](/sdk/fundamentals/unified-api/) (hubs, clients, scopes) and the transaction ingestion model have merits, experience revealed some issues that we categorize into two groups. The first group has to do with scope propagation, in essence the ability to determine what the “current scope” is. This operation is required for both manual instrumentation in user code as well as for automatic instrumentation in SDK integrations. @@ -36,7 +36,7 @@ The second group is for issues related to the wire format used to send transacti _This issue is tracked by [getsentry/sentry-javascript#3751](https://github.com/getsentry/sentry-javascript/issues/3751)._ -The [Unified SDK architecture](https://develop.sentry.dev/sdk/unified-api/) is fundamentally based on the existence of a `hub` per unit of concurrency, each `hub` having a stack of pairs of `client` and `scope`. A `client` holds configuration and is responsible for sending data to Sentry by means of a `transport`, while a `scope` holds contextual data that gets appended to outgoing events, such as tags and breadcrumbs. +The [Unified SDK architecture](/sdk/fundamentals/unified-api/) is fundamentally based on the existence of a `hub` per unit of concurrency, each `hub` having a stack of pairs of `client` and `scope`. A `client` holds configuration and is responsible for sending data to Sentry by means of a `transport`, while a `scope` holds contextual data that gets appended to outgoing events, such as tags and breadcrumbs. Every `hub` knows what the current scope is. It is always the scope on top of the stack. The difficult part is having a `hub` “per unit of concurrency”. diff --git a/src/docs/sdk/performance/span-data-conventions.mdx b/src/docs/sdk/telemetry/tracing/span-data-conventions.mdx similarity index 98% rename from src/docs/sdk/performance/span-data-conventions.mdx rename to src/docs/sdk/telemetry/tracing/span-data-conventions.mdx index 0b054391a3..979a7d6c37 100644 --- a/src/docs/sdk/performance/span-data-conventions.mdx +++ b/src/docs/sdk/telemetry/tracing/span-data-conventions.mdx @@ -38,13 +38,13 @@ Below describes the conventions for the Span interface for the `data` field on t | Attribute | Type | Description | Examples | | --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | | `blocked_main_thread` | boolean | Whether the main thread was blocked by the span. | `true` | -| `call_stack` | StackFrame[] | The most relevant stack frames, that lead to the File I/O span. The stack frame should adhere to the [`StackFrame`](https://develop.sentry.dev/sdk/event-payloads/stacktrace/#frame-attributes) interface. | | +| `call_stack` | StackFrame[] | The most relevant stack frames, that lead to the File I/O span. The stack frame should adhere to the [`StackFrame`](/sdk/protocol/event-payloads/stacktrace/#frame-attributes) interface. | | | `url` | string | The URL of the resource that was fetched. | `https://example.com` | | `type` | string | More granular type of the operation happening. | `fetch` | | `frames.total` | int | The number of total frames rendered during the lifetime of the span. | `60` | | `frames.slow` | int | The number of slow frames rendered during the lifetime of the span. | `2` | | `frames.frozen` | int | The number of frozen frames rendered during the lifetime of the span. | `1` | -| `frames.delay` | number | The sum of all delayed frame durations in seconds during the lifetime of the span. For more information see frames delay. | `1.3246` | +| `frames.delay` | number | The sum of all delayed frame durations in seconds during the lifetime of the span. For more information see frames delay. | `1.3246` | ## Browser diff --git a/src/docs/sdk/performance/span-operations.mdx b/src/docs/sdk/telemetry/tracing/span-operations.mdx similarity index 99% rename from src/docs/sdk/performance/span-operations.mdx rename to src/docs/sdk/telemetry/tracing/span-operations.mdx index 3a3afb9db9..4a5e83a151 100644 --- a/src/docs/sdk/performance/span-operations.mdx +++ b/src/docs/sdk/telemetry/tracing/span-operations.mdx @@ -262,7 +262,6 @@ Messages/Queue spans are expected follow OpenTelemetry's [Messaging](https://git | file | | | function | | | graphql | | -| graphql | | | grpc | | | http | | | mark | | diff --git a/src/docs/sdk/performance/time-to-initial-full-display.mdx b/src/docs/sdk/telemetry/tracing/time-to-initial-full-display.mdx similarity index 100% rename from src/docs/sdk/performance/time-to-initial-full-display.mdx rename to src/docs/sdk/telemetry/tracing/time-to-initial-full-display.mdx diff --git a/src/docs/sdk/performance/trace-origin.mdx b/src/docs/sdk/telemetry/tracing/trace-origin.mdx similarity index 77% rename from src/docs/sdk/performance/trace-origin.mdx rename to src/docs/sdk/telemetry/tracing/trace-origin.mdx index c659ba6a0d..01334ac264 100644 --- a/src/docs/sdk/performance/trace-origin.mdx +++ b/src/docs/sdk/telemetry/tracing/trace-origin.mdx @@ -4,7 +4,7 @@ title: "Trace Origin" Trace origin indicates what created a trace or a span. Not all traces and spans contain enough information to tell whether the user or what precisely in the SDK created it. Origin solves this problem. Origin can be sent with -the trace context or spans. +the trace context or spans. The SDKs should set this value automatically. It is not expected to be set manually by users. The value for origin should rarely change so that we can run proper analytics on them. @@ -19,7 +19,7 @@ that the SDK or some integration created it. `category` -: _Optional_. Is the category of the trace or span, and it must be a category of span operations. For example, `http`, `db`, `ui`, `navigation`, `file`, `browser`, `rpc`, etc. +: _Optional_. Is the category of the trace or span, and it must be a category of span operations. For example, `http`, `db`, `ui`, `navigation`, `file`, `browser`, `rpc`, etc. `integration-name` @@ -54,7 +54,7 @@ All parts can only contain: - `auto.db.core_data` - `auto.db.graphql` -Origins of type `manual` can also have categories and integration names. For example, for the time to display feature, the user manually calls an API of the SDK, +Origins of type `manual` can also have categories and integration names. For example, for the time to display feature, the user manually calls an API of the SDK, creating a span. In this case, the SDK can tell what created the span, but the user did it manually. On the other hand, the SDK also automatically creates a span. In this case we end up with the following origins: @@ -63,6 +63,6 @@ automatically creates a span. In this case we end up with the following origins: ## See also: -- Span Interface -- Trace Context +- Span Interface +- Trace Context - Related [RFC](https://github.com/getsentry/rfcs/pull/73/); \ No newline at end of file diff --git a/src/docs/sdk/distributed-tracing/index.mdx b/src/docs/sdk/telemetry/tracing/trace-propagation/index.mdx similarity index 88% rename from src/docs/sdk/distributed-tracing/index.mdx rename to src/docs/sdk/telemetry/tracing/trace-propagation/index.mdx index ebbe5f70a7..f40ca6c2cb 100644 --- a/src/docs/sdk/distributed-tracing/index.mdx +++ b/src/docs/sdk/telemetry/tracing/trace-propagation/index.mdx @@ -1,12 +1,12 @@ --- -title: "Distributed Tracing" +title: Trace Propagation --- This document describes how a SDK should propagate information between different services to connect all telemetry (errors, profiles, replays, transaction, check-ins, ...) from those services into one trace. For an overview see [Distributed Tracing](https://docs.sentry.io/product/performance/distributed-tracing/) in the product docs. -Sentry uses three containers to hold trace information [`sentry-trace`](/sdk/performance/#header-sentry-trace), [`traceparent`](/sdk/performance/#header-traceparent) and [`baggage`](/sdk/performance/dynamic-sampling-context/#baggage-header). +Sentry uses three containers to hold trace information [`sentry-trace`](/sdk/telemetry/tracing/#header-sentry-trace), [`traceparent`](/sdk/telemetry/tracing/#header-traceparent) and [`baggage`](/sdk/telemetry/tracing/dynamic-sampling-context/#baggage-header). With these containers you can propagate a trace to a down-stream service. By either - adding `sentry-trace`, `traceparent` and `baggage` HTTP headers (when doing outgoing HTTP requests), diff --git a/src/docs/sdk/performance/ui-event-transactions.mdx b/src/docs/sdk/telemetry/tracing/ui-event-transactions.mdx similarity index 100% rename from src/docs/sdk/performance/ui-event-transactions.mdx rename to src/docs/sdk/telemetry/tracing/ui-event-transactions.mdx diff --git a/src/docs/sdk/tooling/index.mdx b/src/docs/sdk/tooling/index.mdx new file mode 100644 index 0000000000..d4fde852d2 --- /dev/null +++ b/src/docs/sdk/tooling/index.mdx @@ -0,0 +1,6 @@ +--- +title: Tooling +sidebar_order: 9500 +--- + + \ No newline at end of file diff --git a/src/docs/sdk/setup-wizards/index.mdx b/src/docs/sdk/tooling/setup-wizards/index.mdx similarity index 99% rename from src/docs/sdk/setup-wizards/index.mdx rename to src/docs/sdk/tooling/setup-wizards/index.mdx index 13ac39c415..b61760d4f8 100644 --- a/src/docs/sdk/setup-wizards/index.mdx +++ b/src/docs/sdk/tooling/setup-wizards/index.mdx @@ -1,6 +1,6 @@ --- title: Setup Wizards -sidebar_order: 21 +sidebar_order: 1 --- Some SDKs support automatic SDK setup with the Sentry Wizard to make setting up the SDK as easy as possible. diff --git a/src/docs/sdk/setup-wizards/setup-wizard-copy-paste.png b/src/docs/sdk/tooling/setup-wizards/setup-wizard-copy-paste.png similarity index 100% rename from src/docs/sdk/setup-wizards/setup-wizard-copy-paste.png rename to src/docs/sdk/tooling/setup-wizards/setup-wizard-copy-paste.png diff --git a/src/docs/sdk/tooling/spotlight/index.mdx b/src/docs/sdk/tooling/spotlight/index.mdx new file mode 100644 index 0000000000..f5b21336ae --- /dev/null +++ b/src/docs/sdk/tooling/spotlight/index.mdx @@ -0,0 +1,8 @@ +--- +title: Spotlight +sidebar_order: 2 +--- + +Documentation for Spotlight can be found on GitHub: +https://github.com/getsentry/spotlight + diff --git a/src/docs/self-hosted/sso.mdx b/src/docs/self-hosted/sso.mdx index 5f484e5dd4..4e357258ee 100644 --- a/src/docs/self-hosted/sso.mdx +++ b/src/docs/self-hosted/sso.mdx @@ -16,7 +16,7 @@ As of Sentry 20.6.0, self-hosted Sentry comes with built-in support for SAML2 an sentry-auth-saml2@https://github.com/getsentry/sentry-auth-saml2/archive/master.zip#egg=sentry-auth-saml2 ``` - The way you can set this up is the same as [sentry.io](https://sentry.io) except, you need to use your own instance's [`url-prefix`](https://develop.sentry.dev/config/#general) for the URLs mentioned in the documentation. + The way you can set this up is the same as [sentry.io](https://sentry.io) except, you need to use your own instance's [`url-prefix`](/config/#general) for the URLs mentioned in the documentation. Please refer to our [main SAML documentation](https://docs.sentry.io/accounts/sso/#saml2-identity-provider) for all the details. diff --git a/src/docs/self-hosted/troubleshooting.mdx b/src/docs/self-hosted/troubleshooting.mdx index feae43a319..1ba97e4fd4 100644 --- a/src/docs/self-hosted/troubleshooting.mdx +++ b/src/docs/self-hosted/troubleshooting.mdx @@ -125,7 +125,7 @@ To see a more complete example, please see [a sample solution on our community f ## Postgres -Postgres is used for the primary datastore, as well as the [nodestore](https://develop.sentry.dev/services/nodestore/) which is used to store key/value data. The `nodestore_node` table can grow rapidly, especially when heavily utilising the Performance Monitoring feature as trace data is stored in this table. +Postgres is used for the primary datastore, as well as the [nodestore](/services/nodestore/) which is used to store key/value data. The `nodestore_node` table can grow rapidly, especially when heavily utilising the Performance Monitoring feature as trace data is stored in this table. The `nodestore_node` table is cleaned up as part of the `cleanup` task, however Postgres may not get a chance to vacuum the table (especially under heavy load), so even the rows may be deleted, they're still taking up space on disk. diff --git a/src/docs/transaction-clustering/index.mdx b/src/docs/transaction-clustering/index.mdx index d85021a511..1d7c19934c 100644 --- a/src/docs/transaction-clustering/index.mdx +++ b/src/docs/transaction-clustering/index.mdx @@ -11,7 +11,7 @@ In terms of technical implementation, it is similar to [Data Scrubbing](/pii/). ## The Problem In our [Performance](https://docs.sentry.io/product/performance/) product, transactions are grouped by their name -(the [`event.transaction`](/sdk/event-payloads/#optional-attributes) field). +(the [`event.transaction`](/sdk/protocol/event-payloads/#optional-attributes) field). This works well as long as the cardinality of distinct transaction names that the SDK sends is low, for example by using the [route of a web framework](https://docs.sentry.io/platforms/javascript/guides/react/configuration/integrations/react-router/) as the transaction name. diff --git a/vercel.json b/vercel.json index 4b9d9f9ece..8ce2331471 100644 --- a/vercel.json +++ b/vercel.json @@ -29,9 +29,12 @@ "redirects": [ { "source": "/sdk/unified-api/tracing/(.*)", - "destination": "/sdk/performance/$1" + "destination": "/sdk/telemetry/tracing/$1" + }, + { + "source": "/onpremise/(.*)", + "destination": "/self-hosted/$1" }, - { "source": "/onpremise/(.*)", "destination": "/self-hosted/$1" }, { "source": "/self-hosted/mail(.*)", "destination": "/self-hosted/email$1" @@ -39,6 +42,86 @@ { "source": "/processing-tickets(/?)", "destination": "https://open.sentry.io/triage/" + }, + { + "source": "/sdk/store/(.*)", + "destination": "/sdk/endpoints/store/$1" + }, + { + "source": "/sdk/rate-limiting/(.*)", + "destination": "/sdk/endpoints/rate-limiting/$1" + }, + { + "source": "/sdk/setup-wizards/(.*)", + "destination": "/sdk/tooling/setup-wizards/$1" + }, + { + "source": "/sdk/profiles/(.*)", + "destination": "/sdk/telemetry/profiles/$1" + }, + { + "source": "/sdk/check-ins/(.*)", + "destination": "/sdk/telemetry/check-ins/$1" + }, + { + "source": "/sdk/metrics/(.*)", + "destination": "/sdk/telemetry/metrics/$1" + }, + { + "source": "/sdk/performance/(.*)", + "destination": "/sdk/telemetry/tracing/$1" + }, + { + "source": "/sdk/distributed-tracing/(.*)", + "destination": "/sdk/telemetry/tracing/trace-propagation/$1" + }, + { + "source": "/sdk/telemetry/tracing/research-performance-api/(.*)", + "destination": "/sdk/telemetry/tracing/research-performance-api/$1" + }, + { + "source": "/sdk/client-reports/(.*)", + "destination": "/sdk/protocol/client-reports/$1" + }, + { + "source": "/sdk/envelopes/(.*)", + "destination": "/sdk/protocol/envelopes/$1" + }, + { + "source": "/sdk/event-payloads/(.*)", + "destination": "/sdk/protocol/event-payloads/$1" + }, + { + "source": "/sdk/sessions/(.*)", + "destination": "/sdk/protocol/sessions/$1" + }, + { + "source": "/sdk/craft-quick-start/(.*)", + "destination": "/sdk/processes/releasing/$1" + }, + { + "source": "/sdk/overview/(.*)", + "destination": "/sdk/processes/development/overview/$1" + }, + { + "source": "/sdk/philosophy/(.*)", + "destination": "/sdk/fundamentals/philosophy/$1" + }, + { + "source": "/sdk/signal-handlers/(.*)", + "destination": "/sdk/fundamentals/reliability/resiliency/signal-handlers/$1" + }, + { + "source": "/sdk/unified-api/(.*)", + "destination": "/sdk/fundamentals/unified-api/$1" + }, + { + "source": "/sdk/serverless/(.*)", + "destination": "/sdk/processes/development/serverless/$1" + }, + { + "source": "/sdk/context-management/(.*)", + "destination": "/sdk/fundamentals/data-handling/context-management/$1" } ] }