diff --git a/docs/platforms/dart/common/configuration/options.mdx b/docs/platforms/dart/common/configuration/options.mdx index dd063a80700e27..798a84d4e6caf2 100644 --- a/docs/platforms/dart/common/configuration/options.mdx +++ b/docs/platforms/dart/common/configuration/options.mdx @@ -240,3 +240,21 @@ String entries do not have to be full matches, meaning the URL of a request is m If is not provided, trace data is attached to every outgoing request from the instrumented client. + + + +If set to `true`, the SDK will only continue a trace when the organization ID in the incoming `baggage` header matches the organization ID of the current Sentry client. + +The client's organization ID is extracted from the DSN or can be explicitly set with the `orgId` option. + +If the organization IDs don't match, the SDK will start a new trace instead of continuing the incoming one. This is useful to prevent traces of unknown third-party services from being continued in your application. + + + + + +The organization ID for your Sentry project. + +The SDK will try to extract the organization ID from the DSN. If it can't be found, or if you need to override it, you can explicitly provide the ID with this option. The organization ID is used for trace propagation and features like `strictTraceContinuation`. + + diff --git a/platform-includes/distributed-tracing/how-to-use/dart.flutter.mdx b/platform-includes/distributed-tracing/how-to-use/dart.flutter.mdx index 9f6d50a1dda417..9c771272e8e223 100644 --- a/platform-includes/distributed-tracing/how-to-use/dart.flutter.mdx +++ b/platform-includes/distributed-tracing/how-to-use/dart.flutter.mdx @@ -1,3 +1,39 @@ If you're using the current version of our Flutter SDK, distributed tracing will work out of the box. If you're using version `7.10.0` or below, you'll need to have our tracing feature enabled in order for distributed tracing to work. + +### Strict Trace Continuation + +When your application communicates with backend services, responses might include `sentry-trace` and `baggage` headers from an upstream service that is also using Sentry. +By default, the SDK will continue the trace from these incoming headers. However, this behavior can be undesirable if the responses are from a third-party service, +as it can lead to unwanted traces, increased billing, and skewed performance data. + +To prevent this, you can enable `strictTraceContinuation`. When this option is set to `true`, the SDK only continues a trace if it belongs to the same Sentry organization. +Otherwise, it starts a new trace. + +```dart {4} +await SentryFlutter.init((options) { + options.dsn = '___PUBLIC_DSN___'; + options.tracesSampleRate = 1.0; + // Ensure that only traces from your own organization are continued + options.strictTraceContinuation = true; +}); +``` + +The SDK automatically parses the organization ID from your DSN. If you use a DSN format that doesn't include the organization ID (number followed by the letter `"o"`), or if you need to override it, you can provide it manually using the `orgId` option: + +```dart {5} +await SentryFlutter.init((options) { + options.dsn = '___PUBLIC_DSN___'; + options.tracesSampleRate = 1.0; + options.strictTraceContinuation = true; + // Manually provide your organization ID (overrides organization ID parsed from DSN) + options.orgId = '12345'; +}); +``` + + + +On iOS, only the Dart layer enforces strict trace continuation. Native iOS coverage will be enabled in a future release. + +