diff --git a/docs/platforms/python/configuration/filtering/index.mdx b/docs/platforms/python/configuration/filtering/index.mdx index 274ead010701ff..07d21fb0e5e92b 100644 --- a/docs/platforms/python/configuration/filtering/index.mdx +++ b/docs/platforms/python/configuration/filtering/index.mdx @@ -68,7 +68,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. @@ -101,24 +102,97 @@ 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 options. These allow you to provide a function to evaluate the current transaction or 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 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. -Learn more about configuring the sample rate. +Learn more about configuring sampling. ### Using + + +Not available in stream mode. Use instead. + + + + +### Using + + + +Only available in stream mode. + + + +Use the configuration option, which lets you provide a function to modify a span. +This function is called for the service span and all child spans. + +If you want to drop the service span, including its child spans, use [`ignore_spans`](#using-ignore-spans). + + + +See `before_send_span` for details. + +### Using + + + +Only available in stream mode. + + + +You can use the option to filter out spans that match a certain pattern by providing a list of strings, compiled regular expressions, or dictionaries. hen using strings, a span name containing the string will be filtered out. For exact or more complex pattern matching, use compiled regular expressions instead. + +You can also provide a dictionary with `name` and/or `attributes` keys to match on multiple conditions. At least one key must be provided. + +```python +import re +import sentry_sdk + +sentry_sdk.init( + _experiments={ + "trace_lifecycle": "stream", + "ignore_spans": [ + # String match against span name + "/health", + + # Regex match against span name + re.compile(r"/flow/.*"), + + # Match by attributes (all must match) + { + "attributes": { + "service.id": "15def9a", + "flow.pipeline": "legacy", + } + }, + + # Match by name and attributes + { + "name": re.compile(r"/flow/.*"), + "attributes": { + "service.id": re.compile(r".*\.facade"), + }, + }, + ], + }, +) +``` + +See `ignore_spans` for details. diff --git a/docs/platforms/python/configuration/options.mdx b/docs/platforms/python/configuration/options.mdx index 9f50bf5b12e2fb..21b5bd1dc03f55 100644 --- a/docs/platforms/python/configuration/options.mdx +++ b/docs/platforms/python/configuration/options.mdx @@ -252,6 +252,45 @@ This function is called with a transaction event object, and can return a modifi + + + + +Only available in stream mode. + + + +This function is called with a span event object and can return a modified span object. Use it, for example, to manually strip PII from spans or filter data from spans before they're sent to Sentry. It can only work with attributes set at span start time. Attributes added later during the span's lifetime are **not available**. + +Note that `before_send_span` can only modify span data, meaning you cannot use it to drop spans. Use [`ignore_spans`](#_experiments.ignore_spans) to drop spans. + + + +```python {tabTitle:Stream Mode} +import sentry_sdk + +def before_send_span(span, hint): + # Runs once per span, as it's flushed. + # Only attributes set at span-creation time are available here. + span["attributes"].update({ + "component_version": "2.0.0", + "deployment_stage": "production", + }) + return span + +sentry_sdk.init( + # ... + _experiments={ + "trace_lifecycle": "stream", + "before_send_span": before_send_span, + }, +) +``` + + + + + This function is called with a 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. @@ -356,7 +395,7 @@ sentry_sdk.init( -A number between `0` and `1`, controlling the percentage chance a given transaction will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions created in the app. Either this or `traces_sampler` must be defined to enable tracing. +A number between `0` and `1`, controlling the percentage chance a given transaction (or service span in stream mode) will be sent to Sentry. (`0` represents 0% while `1` represents 100%.) Applies equally to all transactions and spans created in the app. Either this or `traces_sampler` must be defined to enable tracing. If `traces_sample_rate` is `0`, this means that no new traces will be created. However, if you have another service (for example a JS frontend) that makes requests to your service that include trace information, those traces will be continued and thus transactions will be sent to Sentry. @@ -366,6 +405,70 @@ If you want to disable all tracing you need to set `traces_sample_rate=None`. In + + +Controls how spans are sent to Sentry: + +- In transaction mode (`"static"`, the default), all spans are collected in memory and sent to Sentry as a single transaction once the root span ends. +- In stream mode (`"stream"`), spans are sent in batches as they finish. + + + + + + + +Only available in stream mode. + + + +A list of strings, compiled regular expressions, or dictionaries that shouldn't be sent to Sentry. When using strings, a span name containing the string will be filtered out. For exact or more complex pattern matching, use compiled regular expressions instead. You can also provide a dictionary with `name` and/or `attributes` keys to match on multiple conditions. At least one key must be provided. + +If the dropped span is a service span, its children are dropped too. If it's a child span, only that span is dropped and its children are reparented to the nearest ancestor. +By default, no spans are ignored. + +`ignoreSpans` is evaluated at span start, so only the span name and attributes available at that point are taken into account. Any name updates or additional attributes added while the span is active won't influence whether the span is dropped. + + + +```python +import re +import sentry_sdk + +sentry_sdk.init( + _experiments={ + "trace_lifecycle": "stream", + "ignore_spans": [ + # String match against span name + "/health", + + # Regex match against span name + re.compile(r"/flow/.*"), + + # Match by attributes (all must match) + { + "attributes": { + "service.id": "15def9a", + "flow.pipeline": "legacy", + } + }, + + # Match by name and attributes + { + "name": re.compile(r"/flow/.*"), + "attributes": { + "service.id": re.compile(r".*\.facade"), + }, + }, + ], + }, +) +``` + + + + + An optional property that controls which downstream services receive tracing data, in the form of a `sentry-trace` and a `baggage` header attached to any outgoing HTTP requests. diff --git a/docs/platforms/python/data-management/sensitive-data/index.mdx b/docs/platforms/python/data-management/sensitive-data/index.mdx index a167fca104a693..c93caf0fa344a4 100644 --- a/docs/platforms/python/data-management/sensitive-data/index.mdx +++ b/docs/platforms/python/data-management/sensitive-data/index.mdx @@ -45,9 +45,19 @@ You can use the configuration param -### & +### , , & -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. The SDK also provide a hook which does the same thing for transactions. We recommend using and in the SDK 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. The SDK also provides a hook, that does the same thing for transactions, and a hook, that does the same thing for service spans in stream mode. We recommend using these hooks in the SDK to **scrub any data before it is sent**, to ensure that sensitive data never leaves the local environment. + + + + runs after the entire +transaction finishes, which means it has access to all data set during the +span's lifetime. In contrast, can +only work with attributes set at span start time. Attributes added later during +the span's lifetime aren't available. + + diff --git a/docs/platforms/python/profiling/index.mdx b/docs/platforms/python/profiling/index.mdx index d559abee02dcdb..11c772dd4c7df9 100644 --- a/docs/platforms/python/profiling/index.mdx +++ b/docs/platforms/python/profiling/index.mdx @@ -16,7 +16,10 @@ With [profiling](/product/explore/profiling/), Sentry tracks your software's per Continuous profiling is available starting in SDK version `2.24.1`. -Transaction-based profiling is available starting in SDK version `1.18.0`. + + Transaction-based profiling + +is available starting in SDK version `1.18.0`. @@ -92,6 +95,7 @@ Continuous profiling was experimental in SDK versions prior to `2.24.1` and will Transaction-based profiling is available starting in SDK version `1.18.0`. +It's not available in stream mode. Use continuous profiling instead. diff --git a/docs/platforms/python/sampling.mdx b/docs/platforms/python/sampling.mdx index 6bbece4c0d7d91..b7ab4dc7dcd9c7 100644 --- a/docs/platforms/python/sampling.mdx +++ b/docs/platforms/python/sampling.mdx @@ -42,6 +42,12 @@ You can define at most one of the an ## Sampling Transaction Events + + +If you're using stream mode, refer to our Configure Sampling guide for setup instructions. + + + We recommend sampling your transactions 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. @@ -58,8 +64,8 @@ The Sentry SDKs have two configuration options to control the volume of transact - Uses default [inheritance](#inheritance) and [precedence](#precedence) behavior 2. Sampling function () which: - Samples different transactions at different rates - - Filters out some - transactions entirely + - 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. @@ -105,7 +111,6 @@ sentry_sdk.start_transaction( ) ``` - ## 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. diff --git a/platform-includes/configuration/before-send-span/python.mdx b/platform-includes/configuration/before-send-span/python.mdx new file mode 100644 index 00000000000000..a0e048df54aa36 --- /dev/null +++ b/platform-includes/configuration/before-send-span/python.mdx @@ -0,0 +1,20 @@ +```python +import sentry_sdk + +def postprocess_span(span, hint): + attributes_to_sanitize = [ + "http.request.header.custom-auth", + "http.request.header.custom-user-id", + ] + for attribute in attributes_to_sanitize: + if span["attributes"].get(attribute): + span["attributes"][attribute] = "[Sanitized]" + return span + +sentry_sdk.init( + _experiments={ + "trace_lifecycle": "stream", + "before_send_span": postprocess_span, + }, +) +``` diff --git a/platform-includes/performance/traces-sampler-config-option/python.mdx b/platform-includes/performance/traces-sampler-config-option/python.mdx index 6521295fb60de8..3f9a0f5f22e5d4 100644 --- a/platform-includes/performance/traces-sampler-config-option/python.mdx +++ b/platform-includes/performance/traces-sampler-config-option/python.mdx @@ -1,6 +1,6 @@ -A function responsible for determining the percentage chance a given transaction will be sent to Sentry. This configuration option accepts a function, which takes one parameter (the `sampling_context`). The given `sampling_context` contains information about the transaction and the context in which it's being created. The function 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. +A function responsible for determining the percentage chance a given transaction (or service span in stream mode) will be sent to Sentry. This configuration option accepts a function, which takes one parameter (the `sampling_context`). The given `sampling_context` contains information about the transaction and the context in which it's being created. The function 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 `traces_sample_rate` must be defined to enable tracing. diff --git a/platform-includes/sensitive-data/set-tag/python.mdx b/platform-includes/sensitive-data/set-tag/python.mdx index 49996745df222d..c9c1b015dfa9d6 100644 --- a/platform-includes/sensitive-data/set-tag/python.mdx +++ b/platform-includes/sensitive-data/set-tag/python.mdx @@ -1,3 +1,7 @@ -```python +```python {tabTitle:Transaction Mode(Default)} sentry_sdk.set_tag("birthday", checksum_or_hash("08/12/1990")) ``` + +```python {tabTitle:Stream Mode} +sentry_sdk.set_attribute("birthday", checksum_or_hash("08/12/1990")) +``` diff --git a/platform-includes/sensitive-data/set-user/python.mdx b/platform-includes/sensitive-data/set-user/python.mdx index 94f12fed48c5b9..583e61cbdf5fc9 100644 --- a/platform-includes/sensitive-data/set-user/python.mdx +++ b/platform-includes/sensitive-data/set-user/python.mdx @@ -1,7 +1,15 @@ -```python +```python {tabTitle:Transaction Mode(Default)} sentry_sdk.set_user({"id": user.id}) # or sentry_sdk.set_user({"username": user.username}) ``` + +```python {tabTitle:Stream Mode} +sentry_sdk.set_attribute({"user.id": user.id}) + +# or + +sentry_sdk.set_attribute({"user.username": user.username}) +```