diff --git a/docs/platforms/dart/common/configuration/filtering.mdx b/docs/platforms/dart/common/configuration/filtering.mdx index 10fac3931ca5a..654c698b3fa9f 100644 --- a/docs/platforms/dart/common/configuration/filtering.mdx +++ b/docs/platforms/dart/common/configuration/filtering.mdx @@ -42,7 +42,8 @@ When the SDK creates an event or breadcrumb for transmission, that transmission Hints are available in two places: -1. / +1. / + 2. `eventProcessors` Event and breadcrumb `hints` are objects containing various information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected. @@ -71,26 +72,73 @@ When a string or a non-error object is raised, Sentry creates a synthetic except -## Filtering Transaction Events +## Filtering Transactions and Spans -To prevent certain transactions from being reported to Sentry, use the or configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want. +To prevent certain transactions (or spans in stream mode) from being reported to Sentry, use the , (for transaction mode), or (for stream mode) configuration option. These allow you to provide a function to evaluate the current transaction/service span and drop it if it's not one you want. + +You can also use (for transaction mode) or (for stream mode) to modify transaction/span data. ### Using + + +Not available in stream mode. Use instead. + + + You can use the option to filter out transactions that match a certain pattern. This option receives a list of strings and regular expressions to match against the transaction name. When using strings, partial matches will be filtered out. If you need to filter by exact match, use regex patterns instead. +### Using + + + +Only available in stream mode. + + + +Use the configuration option to modify a span. It runs when each span ends. + +If you want to drop spans, use [](#using-ignore-spans). + +```dart +options.ignoreSpans = [ + IgnoreSpanRule.nameEquals('health-check'), + IgnoreSpanRule.nameStartsWith('internal.'), +]; +``` + +See `beforeSendSpan` for details. + +### Using + + + +Only available in stream mode. + + + +You can use the option to filter out spans by name: + +```dart +options.beforeSendSpan = (span) { + span.removeAttribute('http.request.body'); +}; +``` + +See `ignoreSpans` for details. + ### Using -**Note:** The and config options are mutually exclusive. If you define a to filter out certain transactions, you must also handle the case of non-filtered transactions by returning the rate at which you'd like them sampled. +**Note:** The and config options are mutually exclusive. If you define a to filter out certain transactions/service spans, you must also handle the case of non-filtered transactions/service spans by returning the rate at which you'd like them sampled. In its simplest form, used just for filtering the transaction, it looks like this: -It also allows you to sample different transactions at different rates. +It also allows you to sample different transactions/service spans at different rates. -If the transaction currently being processed has a parent transaction (from an upstream service calling this service), the parent (upstream) sampling decision will always be included in the sampling context data, so that your can choose whether and when to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. See Inheriting the parent sampling decision to learn more. +If the transaction or span currently being processed has a parent (from an upstream service calling this service), the parent's (upstream) sampling decision will always be included in the sampling context data, so that your can choose whether and when to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. See Inheriting the parent sampling decision to learn more. -Learn more about configuring the sample rate. +Learn more about configuring sampling. diff --git a/docs/platforms/dart/common/configuration/options.mdx b/docs/platforms/dart/common/configuration/options.mdx index dce0967cce620..fc44bc03de1e9 100644 --- a/docs/platforms/dart/common/configuration/options.mdx +++ b/docs/platforms/dart/common/configuration/options.mdx @@ -198,6 +198,28 @@ By the time is executed, all scope data + + + + +Only available in stream mode. + + + +This function is called with a span event object `SentrySpanV2` and can return a modified span object. Use it to scrub or modify span attributes before the span is sent to Sentry. Unlike other `beforeSend` callbacks, it can't drop spans — use [`ignoreSpans`](#ignoreSpans) for that. + + + +```dart +options.beforeSendSpan = (span) { + span.removeAttribute('http.request.body'); +}; +``` + + + + + This function is called with an SDK-specific breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object. @@ -227,6 +249,52 @@ A number between `0` and `1`, controlling the percentage chance a given transact A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. Either this or must be defined to enable tracing. + + +In stream mode, the sampling context is different: read the span's `name` and `attributes` from `samplingContext.spanContext` instead of the transaction context. See Streamed Spans for details. + + + + + + + +Controls how spans are collected and sent to Sentry. + +- In transaction mode (`SentryTraceLifecycle.static`, the default), spans are buffered and sent together as a transaction. +- In stream mode (`SentryTraceLifecycle.stream`), spans are sent to Sentry in batches as they finish. + + + + + + + +Only available in stream mode. + + + +A list of `IgnoreSpanRule`s that drop spans whose name matches a rule (`nameEquals`, `nameStartsWith`, `nameContains`, or `nameEndsWith`). `ignoreSpans` is evaluated at span start, so only the span names available at that point are taken into account. When an ignored span has children, the children are re-parented to the nearest recording ancestor rather than dropped. + +| Factory | Matches | +| ---------------------------------------- | --------------------------------- | +| `IgnoreSpanRule.nameEquals(String)` | Exact span name | +| `IgnoreSpanRule.nameStartsWith(Pattern)` | Name prefix (String or RegExp) | +| `IgnoreSpanRule.nameContains(Pattern)` | Name substring (String or RegExp) | +| `IgnoreSpanRule.nameEndsWith(String)` | Name suffix | + + + +```dart +options.ignoreSpans = [ + IgnoreSpanRule.nameEquals('health-check'), + IgnoreSpanRule.nameStartsWith('internal.'), + IgnoreSpanRule.nameContains('metrics'), + IgnoreSpanRule.nameEndsWith('.bg'), +]; +``` + + diff --git a/docs/platforms/dart/common/configuration/sampling.mdx b/docs/platforms/dart/common/configuration/sampling.mdx index e714c315cfb2b..942933c24fbfc 100644 --- a/docs/platforms/dart/common/configuration/sampling.mdx +++ b/docs/platforms/dart/common/configuration/sampling.mdx @@ -22,29 +22,34 @@ Changing the error sample rate requires re-deployment. In addition, setting an S ## Sampling Transaction Events -We recommend sampling your transactions for two reasons: + + +This page covers both transaction mode (default, using transactions) and stream mode (using service spans). See Streamed Spans to learn more. + + + +We recommend sampling your transactions/service spans for two reasons: 1. Capturing a single trace involves minimal overhead, but capturing traces for _every_ page load or _every_ API request may add an undesirable load to your system. 2. Enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor your volume to your organization's needs. -Choose a sampling rate with the goal of finding a balance between performance and volume concerns with data accuracy. You don't want to collect _too_ much data, but you want to collect sufficient data from which to draw meaningful conclusions. If you’re not sure what rate to choose, start with a low value and gradually increase it as you learn more about your traffic patterns and volume. +Choose a sampling rate with the goal of finding a balance between performance and volume concerns with data accuracy. You don't want to collect _too_ much data, but you want to collect sufficient data from which to draw meaningful conclusions. If you're not sure what rate to choose, start with a low value and gradually increase it as you learn more about your traffic patterns and volume. -## Configuring the Transaction Sample Rate +## Configuring the Sample Rate -The Sentry SDKs have two configuration options to control the volume of transactions sent to Sentry, allowing you to take a representative sample: +The Sentry SDKs have two configuration options to control the volume of transactions/service spans sent to Sentry, allowing you to take a representative sample: 1. Uniform sample rate (): - - - Provides an even cross-section of transactions, no matter where in your app or under what circumstances they occur. + - Provides an even cross-section of transactions/service spans, no matter where in your app or under what circumstances they occur. - Uses default [inheritance](#inheritance) and [precedence](#precedence) behavior 2. Sampling function () which: - - Samples different transactions at different rates - - Filters out some - transactions entirely + - Samples different transactions/service spans at different rates + - Filters out + some transactions/service spans entirely - Modifies default [precedence](#precedence) and [inheritance](#inheritance) behavior -By default, none of these options are set, meaning no transactions will be sent to Sentry. You must set either one of the options to start sending transactions. +By default, none of these options are set, meaning no transactions/service spans will be sent to Sentry. You must set either one of the options to start sending them. ### Setting a Uniform Sample Rate @@ -58,23 +63,29 @@ By default, none of these options are set, meaning no transactions will be sent ### Default Sampling Context Data -The information contained in the object passed to the when a transaction is created varies by platform and integration. +The information contained in the object passed to the when a transaction/service span is created varies by platform and integration. ### Custom Sampling Context Data -When using custom instrumentation to create a transaction, you can add data to the by passing it as an optional second argument to . This is useful if there's data to which you want the sampler to have access but which you don't want to attach to the transaction as `tags` or `data`, such as information that's sensitive or that’s too large to send with the transaction. For example: + + +This only applies to transaction mode. In stream mode there's no custom sampling context — pass data as span attributes when you start the span, then read them from `samplingContext.spanContext.attributes` in your `tracesSampler`. See [Setting a Sampling Function](#setting-a-sampling-function). + + + +When using custom instrumentation to create a transaction, you can add data to the by passing it as an optional second argument to . This is useful if there's data to which you want the sampler to have access but which you don't want to attach to the transaction as `tags` or `data`, such as information that's sensitive or that's too large to send with the transaction. For example: ## Inheritance -Whatever a transaction's sampling decision, that decision will be passed to its child spans and from there to any transactions they subsequently cause in other services. +Whatever a transaction's/service span's sampling decision, that decision will be passed to its child spans and from there to any transactions they subsequently cause in other services. (See Distributed Tracing for more about how that propagation is done.) -If the transaction currently being created is one of those subsequent transactions (in other words, if it has a parent transaction), the upstream (parent) sampling decision will be included in the sampling context data. Your can use this information to choose whether to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. +If the transaction/service span currently being created is one of those subsequent transactions/service spans (in other words, if it has a parent transaction/service span), the upstream (parent) sampling decision will be included in the sampling context data. Your can use this information to choose whether to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. @@ -86,23 +97,29 @@ If you're using a rather than a ## Forcing a Sampling Decision + + +This only applies to transaction mode. In stream mode you can't force a decision at span creation — control sampling with a `tracesSampler` that reads the span's `name` and `attributes`. + + + If you know at transaction creation time whether or not you want the transaction sent to Sentry, you also have the option of passing a sampling decision directly to the transaction constructor (note, not in the object). If you do that, the transaction won't be subject to the , nor will be run, so you can count on the decision that's passed not to be overwritten. ## Precedence -There are multiple ways for a transaction to end up with a sampling decision. +There are multiple ways for a transaction/service span to end up with a sampling decision. - Random sampling according to a static sample rate set in - Random sampling according to a sample function rate returned by - Absolute decision (100% chance or 0% chance) returned by -- If the transaction has a parent, inheriting its parent's sampling decision +- If the transaction/service span has a parent, inheriting its parent's sampling decision - Absolute decision passed to When there's the potential for more than one of these to come into play, the following precedence rules apply: 1. If a sampling decision is passed to , that decision will be used, overriding everything else. -1. If is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, use the sampling context data to make its own decision, or choose a sample rate for the transaction. We advise against overriding the parent sampling decision because it will break distributed traces) +1. If is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, use the sampling context data to make its own decision, or choose a sample rate for the transaction/service span. We advise against overriding the parent sampling decision because it will break distributed traces) 1. If is not defined, but there's a parent sampling decision, the parent sampling decision will be used. 1. If is not defined and there's no parent sampling decision, will be used. diff --git a/docs/platforms/dart/common/data-management/sensitive-data/index.mdx b/docs/platforms/dart/common/data-management/sensitive-data/index.mdx index 10a3392579264..b145d84990b10 100644 --- a/docs/platforms/dart/common/data-management/sensitive-data/index.mdx +++ b/docs/platforms/dart/common/data-management/sensitive-data/index.mdx @@ -35,9 +35,9 @@ If you _do not_ wish to use the default PII behavior, you can also choose to ide ## Scrubbing Data -### & +### , , & -SDKs provide a hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. Some SDKs also provide a hook which does the same thing for transactions. We recommend using and in the SDKs to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment. +The SDK provides a hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. It also provides a hook, that does the same thing for transactions, and a hook, that does the same thing for spans in stream mode. We recommend using these hooks in the SDKs to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment. @@ -47,7 +47,7 @@ Sensitive data may appear in the following areas: - Breadcrumbs → Some SDKs (JavaScript and the Java logging integrations, for example) will pick up previously executed log statements. **Do not log PII** if using this feature and including log statements as breadcrumbs in the event. Some backend SDKs will also record database queries, which may need to be scrubbed. Most SDKs will add the HTTP query string and fragment as a data attribute to the breadcrumb, which may need to be scrubbed. - User context → Automated behavior is controlled via . - HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context. -- Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. +- Transaction/Service Span Names → In certain situations, transaction or span names might contain sensitive data. For example, a browser's pageload transaction/service span might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. - HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed. For more details and data filtering instructions, see Filtering Events. diff --git a/docs/platforms/dart/guides/flutter/configuration/filtering.mdx b/docs/platforms/dart/guides/flutter/configuration/filtering.mdx index 2f4e472d0de63..0e347cedd271f 100644 --- a/docs/platforms/dart/guides/flutter/configuration/filtering.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/filtering.mdx @@ -36,7 +36,8 @@ When the SDK creates an event or breadcrumb for transmission, that transmission Hints are available in two places: -1. / +1. / + 2. `eventProcessors` Event and breadcrumb `hints` are objects containing various information used to put together an event or a breadcrumb. Typically `hints` hold the original exception so that additional data can be extracted or grouping can be affected. @@ -87,20 +88,59 @@ If used on a platform other than Web, this setting will be ignored. -## Filtering Transaction Events +## Filtering Transactions and Spans -To prevent certain transactions from being reported to Sentry, use the or configuration option, which allows you to provide a function to evaluate the current transaction and drop it if it's not one you want. +To prevent certain transactions (or spans in stream mode) from being reported to Sentry, use the , (for transaction mode), or (for stream mode) configuration option. These allow you to provide a function to evaluate the current transaction/service span and drop it if it's not one you want. + +You can also use (for transaction mode) or (for stream mode) to modify transaction/span data. ### Using -**Note:** The and config options are mutually exclusive. If you define a to filter out certain transactions, you must also handle the case of non-filtered transactions by returning the rate at which you'd like them sampled. +**Note:** The and config options are mutually exclusive. If you define a to filter out certain transactions/service spans, you must also handle the case of non-filtered transactions/service spans by returning the rate at which you'd like them sampled. -In its simplest form, used just for filtering the transaction, it looks like this: +In its simplest form, used just for filtering the transaction/service span, it looks like this: -It also allows you to sample different transactions at different rates. +It also allows you to sample different transactions/service spans at different rates. + +If the transaction or span currently being processed has a parent (from an upstream service calling this service), the parent's (upstream) sampling decision will always be included in the sampling context data, so that your can choose whether and when to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. See Inheriting the parent sampling decision to learn more. + +Learn more about configuring sampling. + +### Using + + + +Only available in stream mode. + + + +Use the configuration option to modify a span. It runs when each span ends. + +If you want to drop spans, use [](#using-ignore-spans). + +```dart +options.ignoreSpans = [ + IgnoreSpanRule.nameEquals('health-check'), + IgnoreSpanRule.nameStartsWith('internal.'), +]; +``` + +See `beforeSendSpan` for details. + +### Using + + + +Only available in stream mode. + + -If the transaction currently being processed has a parent transaction (from an upstream service calling this service), the parent (upstream) sampling decision will always be included in the sampling context data, so that your can choose whether and when to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. See Inheriting the parent sampling decision to learn more. +You can use the option to filter out spans by name: -Learn more about configuring the sample rate. +```dart +options.beforeSendSpan = (span) { + span.removeAttribute('http.request.body'); +}; +``` diff --git a/docs/platforms/dart/guides/flutter/configuration/options.mdx b/docs/platforms/dart/guides/flutter/configuration/options.mdx index 4143a5a2f7ecd..7195b1771a641 100644 --- a/docs/platforms/dart/guides/flutter/configuration/options.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/options.mdx @@ -225,6 +225,28 @@ By the time is executed, all scope data + + + + +Only available in stream mode. + + + +This function is called with a span event object `SentrySpanV2` and can return a modified span object. Use it to scrub or modify span attributes before the span is sent to Sentry. Unlike other `beforeSend` callbacks, it can't drop spans — use [`ignoreSpans`](#ignoreSpans) for that. + + + +```dart +options.beforeSendSpan = (span) { + span.removeAttribute('http.request.body'); +}; +``` + + + + + This function is called with an SDK-specific breadcrumb object before the breadcrumb is added to the scope. When nothing is returned from the function, the breadcrumb is dropped. To pass the breadcrumb through, return the first argument, which contains the breadcrumb object. @@ -254,6 +276,52 @@ A number between `0` and `1`, controlling the percentage chance a given transact A function responsible for determining the percentage chance a given transaction will be sent to Sentry. It will automatically be passed information about the transaction and the context in which it's being created, and must return a number between `0` (0% chance of being sent) and `1` (100% chance of being sent). Can also be used for filtering transactions, by returning 0 for those that are unwanted. Either this or must be defined to enable tracing. + + +In stream mode, the sampling context is different: read the span's `name` and `attributes` from `samplingContext.spanContext` instead of the transaction context. See Streamed Spans for details. + + + + + + + +Controls how spans are collected and sent to Sentry. + +- In transaction mode (`SentryTraceLifecycle.static`, the default), spans are buffered and sent together as a transaction. +- In stream mode (`SentryTraceLifecycle.stream`), spans are sent to Sentry in batches as they finish. + + + + + + + +Only available in stream mode. + + + +A list of `IgnoreSpanRule`s that drop spans whose name matches a rule (`nameEquals`, `nameStartsWith`, `nameContains`, or `nameEndsWith`). `ignoreSpans` is evaluated at span start, so only the span names available at that point are taken into account. When an ignored span has children, the children are re-parented to the nearest recording ancestor rather than dropped. + +| Factory | Matches | +| ---------------------------------------- | --------------------------------- | +| `IgnoreSpanRule.nameEquals(String)` | Exact span name | +| `IgnoreSpanRule.nameStartsWith(Pattern)` | Name prefix (String or RegExp) | +| `IgnoreSpanRule.nameContains(Pattern)` | Name substring (String or RegExp) | +| `IgnoreSpanRule.nameEndsWith(String)` | Name suffix | + + + +```dart +options.ignoreSpans = [ + IgnoreSpanRule.nameEquals('health-check'), + IgnoreSpanRule.nameStartsWith('internal.'), + IgnoreSpanRule.nameContains('metrics'), + IgnoreSpanRule.nameEndsWith('.bg'), +]; +``` + + diff --git a/docs/platforms/dart/guides/flutter/configuration/sampling.mdx b/docs/platforms/dart/guides/flutter/configuration/sampling.mdx index 9e06bc53fd237..de8eabbd5c3ed 100644 --- a/docs/platforms/dart/guides/flutter/configuration/sampling.mdx +++ b/docs/platforms/dart/guides/flutter/configuration/sampling.mdx @@ -22,29 +22,34 @@ Changing the error sample rate requires re-deployment. In addition, setting an S ## Sampling Transaction Events -We recommend sampling your transactions for two reasons: + + +This page covers both transaction mode (default, using transactions) and stream mode (using service spans). See Streamed Spans to learn more. + + + +We recommend sampling your transactions/service spans for two reasons: 1. Capturing a single trace involves minimal overhead, but capturing traces for _every_ page load or _every_ API request may add an undesirable load to your system. 2. Enabling sampling allows you to better manage the number of events sent to Sentry, so you can tailor your volume to your organization's needs. -Choose a sampling rate with the goal of finding a balance between performance and volume concerns with data accuracy. You don't want to collect _too_ much data, but you want to collect sufficient data from which to draw meaningful conclusions. If you’re not sure what rate to choose, start with a low value and gradually increase it as you learn more about your traffic patterns and volume. +Choose a sampling rate with the goal of finding a balance between performance and volume concerns with data accuracy. You don't want to collect _too_ much data, but you want to collect sufficient data from which to draw meaningful conclusions. If you're not sure what rate to choose, start with a low value and gradually increase it as you learn more about your traffic patterns and volume. -## Configuring the Transaction Sample Rate +## Configuring the Sample Rate -The Sentry SDKs have two configuration options to control the volume of transactions sent to Sentry, allowing you to take a representative sample: +The Sentry SDKs have two configuration options to control the volume of transactions/service spans sent to Sentry, allowing you to take a representative sample: 1. Uniform sample rate (): - - - Provides an even cross-section of transactions, no matter where in your app or under what circumstances they occur. + - Provides an even cross-section of transactions/service spans, no matter where in your app or under what circumstances they occur. - Uses default [inheritance](#inheritance) and [precedence](#precedence) behavior 2. Sampling function () which: - - Samples different transactions at different rates - - Filters out some - transactions entirely + - Samples different transactions/service spans at different rates + - Filters out + some transactions entirely - Modifies default [precedence](#precedence) and [inheritance](#inheritance) behavior -By default, none of these options are set, meaning no transactions will be sent to Sentry. You must set either one of the options to start sending transactions. +By default, none of these options are set, meaning no transactions/service spans will be sent to Sentry. You must set either one of the options to start sending them. ### Setting a Uniform Sample Rate @@ -58,23 +63,29 @@ By default, none of these options are set, meaning no transactions will be sent ### Default Sampling Context Data -The information contained in the object passed to the when a transaction is created varies by platform and integration. +The information contained in the object passed to the when a transaction/service span is created varies by platform and integration. ### Custom Sampling Context Data + + +This only applies to transaction mode. In stream mode there's no custom sampling context — pass data as span attributes when you start the span, then read them from `samplingContext.spanContext.attributes` in your `tracesSampler`. See [Setting a Sampling Function](#setting-a-sampling-function). + + + When using custom instrumentation to create a transaction, you can add data to the by passing it as an optional second argument to . This is useful if there's data to which you want the sampler to have access but which you don't want to attach to the transaction as `tags` or `data`, such as information that's sensitive or that’s too large to send with the transaction. For example: ## Inheritance -Whatever a transaction's sampling decision, that decision will be passed to its child spans and from there to any transactions they subsequently cause in other services. +Whatever a transaction's/service span's sampling decision, that decision will be passed to its child spans and from there to any transactions/service spans they subsequently cause in other services. (See Distributed Tracing for more about how that propagation is done.) -If the transaction currently being created is one of those subsequent transactions (in other words, if it has a parent transaction), the upstream (parent) sampling decision will be included in the sampling context data. Your can use this information to choose whether to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. +If the transaction/service span currently being created is one of those subsequent transactions/service spans (in other words, if it has a parent transaction/service span), the upstream (parent) sampling decision will be included in the sampling context data. Your can use this information to choose whether to inherit that decision. In most cases, inheritance is the right choice, to avoid breaking distributed traces. A broken trace will not include all your services. @@ -86,23 +97,29 @@ If you're using a rather than a ## Forcing a Sampling Decision + + +This only applies to transaction mode. In stream mode you can't force a decision at span creation — control sampling with a `tracesSampler` that reads the span's `name` and `attributes`. + + + If you know at transaction creation time whether or not you want the transaction sent to Sentry, you also have the option of passing a sampling decision directly to the transaction constructor (note, not in the object). If you do that, the transaction won't be subject to the , nor will be run, so you can count on the decision that's passed not to be overwritten. ## Precedence -There are multiple ways for a transaction to end up with a sampling decision. +There are multiple ways for a transaction/service span to end up with a sampling decision. - Random sampling according to a static sample rate set in - Random sampling according to a sample function rate returned by - Absolute decision (100% chance or 0% chance) returned by -- If the transaction has a parent, inheriting its parent's sampling decision +- If the transaction/service span has a parent, inheriting its parent's sampling decision - Absolute decision passed to When there's the potential for more than one of these to come into play, the following precedence rules apply: 1. If a sampling decision is passed to , that decision will be used, overriding everything else. -1. If is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, use the sampling context data to make its own decision, or choose a sample rate for the transaction. We advise against overriding the parent sampling decision because it will break distributed traces) +1. If is defined, its decision will be used. It can choose to keep or ignore any parent sampling decision, use the sampling context data to make its own decision, or choose a sample rate for the transaction/service span. We advise against overriding the parent sampling decision because it will break distributed traces) 1. If is not defined, but there's a parent sampling decision, the parent sampling decision will be used. 1. If is not defined and there's no parent sampling decision, will be used. diff --git a/docs/platforms/dart/guides/flutter/data-management/sensitive-data/index.mdx b/docs/platforms/dart/guides/flutter/data-management/sensitive-data/index.mdx index 10a3392579264..f6f1128abcc8c 100644 --- a/docs/platforms/dart/guides/flutter/data-management/sensitive-data/index.mdx +++ b/docs/platforms/dart/guides/flutter/data-management/sensitive-data/index.mdx @@ -35,9 +35,9 @@ If you _do not_ wish to use the default PII behavior, you can also choose to ide ## Scrubbing Data -### & +### , , & -SDKs provide a hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. Some SDKs also provide a hook which does the same thing for transactions. We recommend using and in the SDKs to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment. +The SDK provides a hook, which is invoked before an error or message event is sent and can be used to modify event data to remove sensitive information. It also provides a hook, that does the same thing for transactions, and a hook, that does the same thing for spans in stream mode. We recommend using these hooks in the SDKs to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment. @@ -47,7 +47,7 @@ Sensitive data may appear in the following areas: - Breadcrumbs → Some SDKs (JavaScript and the Java logging integrations, for example) will pick up previously executed log statements. **Do not log PII** if using this feature and including log statements as breadcrumbs in the event. Some backend SDKs will also record database queries, which may need to be scrubbed. Most SDKs will add the HTTP query string and fragment as a data attribute to the breadcrumb, which may need to be scrubbed. - User context → Automated behavior is controlled via . - HTTP context → Query strings may be picked up in some frameworks as part of the HTTP request context. -- Transaction Names → In certain situations, transaction names might contain sensitive data. For example, a browser's pageload transaction might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. +- Transaction/Service Span Names → In certain situations, transaction and span names might contain sensitive data. For example, a browser's pageload transaction/service span might have a raw URL like `/users/1234/details` as its name (where `1234` is a user id, which may be considered PII). In most cases, our SDKs can parameterize URLs and routes successfully, that is, turn `/users/1234/details` into `/users/:userid/details`. However, depending on the framework, your routing configuration, race conditions, and a few other factors, the SDKs might not be able to completely parameterize all of your URLs. - HTTP Spans → Most SDKs will include the HTTP query string and fragment as a data attribute, which means the HTTP span may need to be scrubbed. For more details and data filtering instructions, see Filtering Events. diff --git a/docs/platforms/dart/guides/flutter/profiling/index.mdx b/docs/platforms/dart/guides/flutter/profiling/index.mdx index c092562d3ec24..16c932371841e 100644 --- a/docs/platforms/dart/guides/flutter/profiling/index.mdx +++ b/docs/platforms/dart/guides/flutter/profiling/index.mdx @@ -21,7 +21,6 @@ Flutter Profiling is currently in Alpha and available only for **iOS** and **mac Profiling depends on Sentry’s Tracing product being enabled beforehand. To enable tracing in the SDK: - ```dart {diff} SentryFlutter.init( (options) => { @@ -39,7 +38,6 @@ Check out the tracing setup documentation { diff --git a/platform-includes/performance/sampling-function-intro/dart.flutter.mdx b/platform-includes/performance/sampling-function-intro/dart.flutter.mdx index bd4744dadd4f8..88e01f9394979 100644 --- a/platform-includes/performance/sampling-function-intro/dart.flutter.mdx +++ b/platform-includes/performance/sampling-function-intro/dart.flutter.mdx @@ -1,3 +1,5 @@ -To use the sampling function, set the option in your `SentryFlutter.init()` to a function that will accept a dictionary and return a sample rate between 0 and 1. For example: +To use the sampling function, set the option in your `SentryFlutter.init()` to a function that will accept a dictionary and return a sample rate between 0 and 1. + +In stream mode, receives a different context – read the span's `name` and `attributes` form `samplingContext.spanContext`. diff --git a/platform-includes/performance/sampling-function-intro/dart.mdx b/platform-includes/performance/sampling-function-intro/dart.mdx index b8b6f0787f233..346923fa55004 100644 --- a/platform-includes/performance/sampling-function-intro/dart.mdx +++ b/platform-includes/performance/sampling-function-intro/dart.mdx @@ -1,3 +1,5 @@ -To use the sampling function, set the option in your `Sentry.init()` to a function that will accept a dictionary and return a sample rate between 0 and 1. For example: +To use the sampling function, set the option in your `Sentry.init()` to a function that will accept a dictionary and return a sample rate between 0 and 1. + +In stream mode, receives a different context – read the span's `name` and `attributes` form `samplingContext.spanContext`. diff --git a/platform-includes/performance/traces-sampler-as-sampler/dart.flutter.mdx b/platform-includes/performance/traces-sampler-as-sampler/dart.flutter.mdx index 3473d23fc10af..513ed5cc7dc08 100644 --- a/platform-includes/performance/traces-sampler-as-sampler/dart.flutter.mdx +++ b/platform-includes/performance/traces-sampler-as-sampler/dart.flutter.mdx @@ -1,4 +1,4 @@ -```dart +```dart {tabTitle: Transaction Mode (Default)} await SentryFlutter.init((options) { // Determine traces sample rate based on the sampling context options.tracesSampler = (samplingContext) { @@ -26,3 +26,15 @@ await SentryFlutter.init((options) { }; }); ``` + +```dart {tabTitle: Stream Mode} +await SentryFlutter.init((options) { + options.tracesSampler = (samplingContext) { + final spanContext = samplingContext.spanContext; + if (spanContext.name == 'health-check') { + return 0.0; + } + return 0.2; + }; +}); +``` diff --git a/platform-includes/performance/traces-sampler-as-sampler/dart.mdx b/platform-includes/performance/traces-sampler-as-sampler/dart.mdx index 0cee6321597ec..b03736afdac1b 100644 --- a/platform-includes/performance/traces-sampler-as-sampler/dart.mdx +++ b/platform-includes/performance/traces-sampler-as-sampler/dart.mdx @@ -1,4 +1,4 @@ -```dart +```dart {tabTitle: Transaction Mode (Default)} await Sentry.init((options) { // Determine traces sample rate based on the sampling context options.tracesSampler = (samplingContext) { @@ -26,3 +26,15 @@ await Sentry.init((options) { }; }); ``` + +```dart {tabTitle: Stream Mode} +await Sentry.init((options) { + options.tracesSampler = (samplingContext) { + final spanContext = samplingContext.spanContext; + if (spanContext.name == 'health-check') { + return 0.0; + } + return 0.2; + }; +}); +``` diff --git a/platform-includes/performance/uniform-sample-rate/dart.flutter.mdx b/platform-includes/performance/uniform-sample-rate/dart.flutter.mdx index 94c98d1375c13..4d45876ced37c 100644 --- a/platform-includes/performance/uniform-sample-rate/dart.flutter.mdx +++ b/platform-includes/performance/uniform-sample-rate/dart.flutter.mdx @@ -1,3 +1,3 @@ -To do this, set the option in your `SentryFlutter.init()` to a number between 0 and 1. With this option set, every transaction created will have that percentage chance of being sent to Sentry. (So, for example, if you set to `0.2`, approximately 20% of your transactions will get recorded and sent.) That looks like this: +To do this, set the option in your `SentryFlutter.init()` to a number between 0 and 1. With this option set, every transaction/service span created will have that percentage chance of being sent to Sentry. (So, for example, if you set to `0.2`, approximately 20% of your transactions/service spans will get recorded and sent.) That looks like this: diff --git a/platform-includes/performance/uniform-sample-rate/dart.mdx b/platform-includes/performance/uniform-sample-rate/dart.mdx index 3d580beee6739..b2d9024b11879 100644 --- a/platform-includes/performance/uniform-sample-rate/dart.mdx +++ b/platform-includes/performance/uniform-sample-rate/dart.mdx @@ -1,3 +1,3 @@ -To do this, set the option in your `Sentry.init()` to a number between 0 and 1. With this option set, every transaction created will have that percentage chance of being sent to Sentry. (So, for example, if you set to `0.2`, approximately 20% of your transactions will get recorded and sent.) That looks like this: +To do this, set the option in your `Sentry.init()` to a number between 0 and 1. With this option set, every transaction/service span created will have that percentage chance of being sent to Sentry. (So, for example, if you set to `0.2`, approximately 20% of your transactions/service spans will get recorded and sent.) That looks like this: