本技能用于把 Python SDK 从默认的基于 transaction 的追踪生命周期（static）迁移到 span streaming（stream）。在 span streaming 模式下，span 在完成时逐个发送，而不是在结束时批量打包进一个 transaction。
本技能针对 Python SDK。JavaScript 和 Dart/Flutter 有各自的对应版本。
适用时机
当用户提出以下需求时可调用本技能：
- 在 Python 项目中要求“enable span streaming”或“migrate to span streaming”
- 希望从基于 transaction 的追踪切换为流式 span 投递
- 提到 trace_lifecycle、sentry_sdk.traces 或新的 start_span API
- 希望降低 span 投递延迟或实现按 span 处理
环境探测
先通过 grep 查找 sentry_sdk.init 调用、start_span / start_transaction / start_child 使用、@trace 装饰器、continue_trace、before_send_transaction、直接导入 Span / Transaction 类、span 上的 set_data / set_tag / set_context、scope.span / scope.transaction / containing_transaction 访问，以及 get_trace_context 使用，以确定需要迁移的文件范围。
如果代码库中需要迁移的文件很多，可为各迁移类别（span 创建、span 数据、追踪传播等）或各模块/包分配子代理并行处理，每个子代理接收本技能中相应的迁移规则，并操作各自独立的文件集合。
启用 span streaming
前置条件：sentry-sdk >= 2.66.0，且已启用 tracing（配置了 traces_sample_rate 或 traces_sampler）。
在所有 sentry_sdk.init() 调用中添加顶层选项 trace_lifecycle="stream"。
span streaming 需要使用新的 sentry_sdk.traces.start_span API。旧的 sentry_sdk.start_span 和 sentry_sdk.start_transaction API 不会流式发送 span。
迁移 span 创建
- start_span：把 sentry_sdk.start_span() 替换为 sentry_sdk.traces.start_span()，或修改导入。新 API 接受 name（必填）、attributes、parent_span（默认当前活动 span）、active（默认 True）。不再有 description 参数（改用 name），不再支持 op 参数（改用 sentry.op 属性）。
- start_transaction：替换为 sentry_sdk.traces.start_span()，并设置 parent_span=None 使其成为根 span。
- start_child：span.start_child() 不再存在；在父 span 活动期间直接启动新 span 即自动成为子 span。需要显式控制父子关系时使用 parent_span。
- @trace：将导入从 sentry_sdk 改为 sentry_sdk.traces。新装饰器还接受可选的 name（默认函数名）、attributes 和 active。
- get_current_span：改为从 sentry_sdk.traces 导入。
- scope.span 与 scope.transaction：改用 sentry_sdk.traces.get_current_span()；根 span 可通过 get_current_span()._segment 获取（私有 API，尽量重构避免使用）。
- span.containing_transaction：不再存在，改用 span._segment 获取根 span。
- Span 与 Transaction 类：直接导入时（如用于类型标注）替换为 StreamedSpan（from sentry_sdk.traces import StreamedSpan）。
- get_trace_context：流式 span 不再有该方法。只需特定字段时直接访问 span.trace_id / span.span_id 等属性；确实需要完整上下文字典时使用私有方法 span._get_trace_context()。
迁移 span 数据
在 span streaming 模式下，span 没有 contexts、data 或 tags，一切皆为 span 属性。属性键为字符串，值必须是 int、bool、str、float 或这些类型的数组，不支持 None。set_attribute 只支持基本类型；非基本类型需要字符串化或拆分为多个基本类型属性。
- set_data 替换为 set_attribute；
- set_tag 替换为 set_attribute；
- 连续多个 set_data / set_tag 可合并为一次 set_attributes() 调用；
- set_context 中的字典不支持，需展平为独立属性；
- 使用 sentry_sdk.set_tag() 设置的 scope 级 tag 不会应用到流式 span，应改用 sentry_sdk.set_attribute()。
批量操作示例中可使用 set_attribute、set_attributes 和 remove_attribute。span 状态只能是 ok（默认）或 error。
迁移追踪传播
sentry_sdk.traces.continue_trace() 取代旧的 sentry_sdk.continue_trace()，它不再是上下文管理器，只设置传播上下文，由下一个 span 自动接续。要开启全新追踪，使用 sentry_sdk.traces.new_trace()。
迁移采样
使用 traces_sample_rate 时无需改动。使用自定义 traces_sampler 时，采样上下文结构不同：sampling_context["span_context"] 包含 name、trace_id、parent_span_id、parent_sampled、attributes。采样决策在调用 start_span() 时做出，子 span 继承父 span 的决策，除非被 ignore_spans 过滤。
自定义采样上下文不再是 start_span 的参数，而是在启动 span 前通过 sentry_sdk.Scope.set_custom_sampling_context() 设置在 scope 上，且必须在 continue_trace（会重置传播上下文）之后、start_span（采样发生时机）之前设置。
配置 ignore_spans（可选）
ignore_spans 在 span 创建时过滤，规则可以是字符串、已编译正则，或包含 name 和/或 attributes 条件的字典。仅在 trace_lifecycle="stream" 启用时生效，否则 SDK 会发出警告并忽略该选项。匹配只基于创建时设置的 span 名称和属性；若被忽略的是顶层 span，其整个子树也会被忽略；非顶层 span 被忽略时，其子 span 不会自动被忽略，除非自身匹配规则。
迁移 before_send_transaction
before_send_transaction 在流式模式下无效。需注意：旧模型中它在整个 transaction 结束后运行，可访问 span 生命周期内设置的全部数据（如 HTTP 状态码、响应大小、最终结果）；流式模式下替代方案（ignore_spans 与 before_send_span）只能使用 span 启动时设置的属性，后期设置的属性不可用。若过滤逻辑依赖启动后设置的属性，则无法在流式模式下复现，必须移除，可考虑迁移到服务端机制（如 Sentry 入站数据过滤器或 Relay 规则）。迁移逻辑后应从 sentry_sdk.init() 中移除 before_send_transaction。
配置 before_send_span（可选）
before_send_span 允许在 span 离开 SDK 前修改 span，例如脱敏敏感值。它接收 span 和 hint 参数，且必须返回一个 span。
适用场景与限制
适用于 Python 项目从 transaction 批量追踪迁移到逐个 span 流式投递，以获得更低延迟的 span 投递和按 span 处理能力。使用时需注意 SDK 版本与 tracing 前置条件、旧 API 不再流式发送、属性类型限制、私有 API 的稳定性风险，以及 before_send_transaction 相关过滤逻辑在流式模式下可能无法保留。具体价格、收费与部署方式本资料暂未提供。