As long as an integration interacts with tracing in some way (either creates spans on its own, or enriches existing spans with data), it needs to be migrated.
If an integration doesn't do anything tracing-related, e.g. because it's errors-only, feel free to just close the related issue.
⚠️ Careful though with stuff like event processors or tags — even if the integration doesn't appear to be interacting with tracing directly, some mechanisms still put stuff on the transaction, and that data should be ported to appear on the segment span in streaming mode.
Goal
- The integration sends transactions without breaking anything in non-streaming (legacy) mode
- In streaming mode, the integration uses the new v2 pipeline and streams spans
- The data on the spans is comparable in both modes
- Any span attributes set by the integration follow our semantic conventions
- Tests test the integration in both legacy and streaming mode and pass in both modes
How to migrate
- As the core logic is now merged, open a feature branch against
master.
- You can check whether you're currently in legacy or streaming mode via
has_span_streaming_enabled from tracing_utils.
- All
start_span calls have to be duplicated. In legacy mode, preserve old functionality. In streaming mode, use sentry_sdk.traces.start_span with the new signature. Make sure to migrate starting data like op, origin to starting attributes (sentry.op).
- Keep existing
continue_trace usage for legacy mode. In streaming mode, use the new continue_trace that's not a context manager.
- Migrate
custom_sampling_context. It should use Scope.set_custom_sampling_context in streaming mode. Make sure it's set before the span is created as that's when it'll be sampled (and when custom sampling context needs to be available in the traces sampler).
- Keep any event processors as they are, as they're still needed for event-based telemetry like errors. In streaming mode, make sure equivalent data is set on the span directly.
- Avoid setting integration-level attributes on the scope via
scope.set_attribute, as it'd then also be applied to metrics and logs as well as any children of the current span. See https://develop.sentry.dev/sdk/telemetry/spans/span-protocol/#common-attribute-keys for what attributes should be set on all spans. Other attributes should NOT be set on all spans. For instance, request related attributes should only be set on the segment span.
- When translating old contexts, data, tags etc. to span attributes, follow Sentry conventions. If anything is unclear or there's an attribute missing, raise on Slack in
#proj-span-first-sentry as product folks also need to be aligned on attribute changes.
- Parametrize all tests that deal with tracing to execute both in legacy and in span streaming mode. Add equivalent assertions in streaming mode. You can use the
capture_items fixture for unwrapping envelope items automatically.
There is also a comprehensive migration guide: https://sentry-docs-git-ivana-span-first-migration-guide.sentry.dev/platforms/python/migration/span-first/
Prototypes
List of integrations
Prioritize
These appear to be used in Seer. Let's start with them to be able to dogfood Seer again soon.
The rest
As long as an integration interacts with tracing in some way (either creates spans on its own, or enriches existing spans with data), it needs to be migrated.
If an integration doesn't do anything tracing-related, e.g. because it's errors-only, feel free to just close the related issue.
Goal
How to migrate
master.has_span_streaming_enabledfromtracing_utils.start_spancalls have to be duplicated. In legacy mode, preserve old functionality. In streaming mode, usesentry_sdk.traces.start_spanwith the new signature. Make sure to migrate starting data likeop,originto starting attributes (sentry.op).continue_traceusage for legacy mode. In streaming mode, use the newcontinue_tracethat's not a context manager.custom_sampling_context. It should useScope.set_custom_sampling_contextin streaming mode. Make sure it's set before the span is created as that's when it'll be sampled (and when custom sampling context needs to be available in the traces sampler).scope.set_attribute, as it'd then also be applied to metrics and logs as well as any children of the current span. See https://develop.sentry.dev/sdk/telemetry/spans/span-protocol/#common-attribute-keys for what attributes should be set on all spans. Other attributes should NOT be set on all spans. For instance, request related attributes should only be set on the segment span.#proj-span-first-sentryas product folks also need to be aligned on attribute changes.capture_itemsfixture for unwrapping envelope items automatically.There is also a comprehensive migration guide: https://sentry-docs-git-ivana-span-first-migration-guide.sentry.dev/platforms/python/migration/span-first/
Prototypes
List of integrations
Prioritize
These appear to be used in Seer. Let's start with them to be able to dogfood Seer again soon.
The rest