From b67228a61f794b1a7c7d7afcd72209698fa42dca Mon Sep 17 00:00:00 2001 From: Erica Pisani Date: Tue, 14 Jul 2026 13:37:47 -0400 Subject: [PATCH 1/2] docs(span-streaming): Use top-level trace_lifecycle and ignore_spans in Python skill Update the Python span-streaming migration skill to document the new top-level sentry_sdk.init() parameters instead of nesting them under _experiments. Rewrite the enable, sampling, ignore_spans, minimal setup, and checklist examples to use trace_lifecycle="stream" and ignore_spans=[...] directly. Add a Common Issues entry for the new warning emitted when ignore_spans is set without span streaming enabled. before_send_span remains under _experiments since it was not promoted. Fixes PY-2611 Fixes GH-6823 Refs PY-2609 Refs GH-6820 --- .../sentry-span-streaming-python/SKILL.md | 67 +++++++++---------- 1 file changed, 32 insertions(+), 35 deletions(-) diff --git a/skills-legacy/sentry-span-streaming-python/SKILL.md b/skills-legacy/sentry-span-streaming-python/SKILL.md index ccd60e24..57c2c0ab 100644 --- a/skills-legacy/sentry-span-streaming-python/SKILL.md +++ b/skills-legacy/sentry-span-streaming-python/SKILL.md @@ -64,7 +64,7 @@ After detecting the environment, assess how many files need changes. If the code **Prerequisites:** `sentry-sdk` `>=2.62.0` with tracing enabled (`traces_sample_rate` or `traces_sampler` configured). -Add `trace_lifecycle` to `_experiments` in ALL occurences of `sentry_sdk.init()`: +Add the top-level `trace_lifecycle` option in ALL occurences of `sentry_sdk.init()`: ```python import sentry_sdk @@ -79,9 +79,7 @@ sentry_sdk.init( sentry_sdk.init( dsn="...", traces_sample_rate=1.0, - _experiments={ - "trace_lifecycle": "stream", - }, + trace_lifecycle="stream", ) ``` @@ -474,7 +472,7 @@ def traces_sampler(sampling_context): sentry_sdk.init( traces_sampler=traces_sampler, - _experiments={"trace_lifecycle": "stream"}, + trace_lifecycle="stream", ) ``` @@ -516,35 +514,35 @@ 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"), - }, + 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"), }, - ], - }, + }, + ], ) ``` +`ignore_spans` only takes effect when `trace_lifecycle="stream"` is enabled. If it is set without span streaming, the SDK emits a warning and the option is ignored. + Only the span name and attributes set at creation time are available for matching — attributes added later in the span's lifetime are not considered. If an ignored span is a top-level span, its entire subtree is also ignored. If a non-top-level span is ignored, its children are not automatically ignored unless they match a rule themselves. @@ -584,8 +582,8 @@ def postprocess_span(span, hint): return span sentry_sdk.init( + trace_lifecycle="stream", _experiments={ - "trace_lifecycle": "stream", "before_send_span": postprocess_span, }, ) @@ -614,6 +612,7 @@ Instruct the user to verify: | `AttributeError` on `containing_transaction` | Attribute removed in streaming mode | Use `span._segment` | | `AttributeError` on `get_trace_context` | Method removed in streaming mode | Use `span.trace_id` / `span.span_id` directly, or `span._get_trace_context()` | | `before_send_transaction` not called | Expected in streaming mode | Migrate logic to `before_send_span` or `ignore_spans` | +| Warning: `ignore_spans` only works with `trace_lifecycle` set to `stream` | `ignore_spans` set without span streaming enabled | Enable streaming with `trace_lifecycle="stream"`, or remove `ignore_spans` | | `before_send_transaction` logic relied on late-set attributes (e.g. status code) | These attributes aren't available at span creation time | Remove the logic or use server-side filtering (Sentry inbound filters / Relay rules) | ### Quick Reference @@ -626,9 +625,7 @@ import sentry_sdk sentry_sdk.init( dsn="__DSN__", traces_sample_rate=1.0, - _experiments={ - "trace_lifecycle": "stream", - }, + trace_lifecycle="stream", ) ``` @@ -644,7 +641,7 @@ with start_span(name="my operation", attributes={"sentry.op": "task"}) as span: #### Migration Checklist - [ ] SDK version is `>=2.62.0` -- [ ] Added `_experiments={"trace_lifecycle": "stream"}` to `sentry_sdk.init()` +- [ ] Added top-level `trace_lifecycle="stream"` to `sentry_sdk.init()` - [ ] `sentry_sdk.start_span()` migrated to `sentry_sdk.traces.start_span()` - [ ] `sentry_sdk.start_transaction()` migrated to `sentry_sdk.traces.start_span()` - [ ] `span.start_child()` migrated to `sentry_sdk.traces.start_span()` From aca4fa9c61d5a2887e0fe5ff0dc9941a0bb411c3 Mon Sep 17 00:00:00 2001 From: Erica Pisani Date: Wed, 15 Jul 2026 13:29:31 -0400 Subject: [PATCH 2/2] update version to the number that will be the minimum pending SDK release --- skills-legacy/sentry-span-streaming-python/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/skills-legacy/sentry-span-streaming-python/SKILL.md b/skills-legacy/sentry-span-streaming-python/SKILL.md index 57c2c0ab..c8bd91b4 100644 --- a/skills-legacy/sentry-span-streaming-python/SKILL.md +++ b/skills-legacy/sentry-span-streaming-python/SKILL.md @@ -62,7 +62,7 @@ After detecting the environment, assess how many files need changes. If the code ### Enable Span Streaming -**Prerequisites:** `sentry-sdk` `>=2.62.0` with tracing enabled (`traces_sample_rate` or `traces_sampler` configured). +**Prerequisites:** `sentry-sdk` `>=2.66.0` with tracing enabled (`traces_sample_rate` or `traces_sampler` configured). Add the top-level `trace_lifecycle` option in ALL occurences of `sentry_sdk.init()`: @@ -640,7 +640,7 @@ with start_span(name="my operation", attributes={"sentry.op": "task"}) as span: #### Migration Checklist -- [ ] SDK version is `>=2.62.0` +- [ ] SDK version is `>=2.66.0` - [ ] Added top-level `trace_lifecycle="stream"` to `sentry_sdk.init()` - [ ] `sentry_sdk.start_span()` migrated to `sentry_sdk.traces.start_span()` - [ ] `sentry_sdk.start_transaction()` migrated to `sentry_sdk.traces.start_span()`