用途:把 Sentry 默认的事务型追踪生命周期(static)迁移为跨度流式生命周期(stream),跨度在完成时即分批发送,而非在结束时合并为单个事务,从而实现更低的跨度投递延迟与逐跨度处理。适用触发场景包括用户要求启用跨度流式、迁移到跨度流式,或提及 traceLifecycle、spanStreamingIntegration、withStreamedSpan。
主要能力:该技能分阶段执行——检测平台与 SDK 版本、查找现有 Sentry 配置与 beforeSendSpan/beforeSendTransaction/ignoreSpans 使用情况;随后按环境迁移;最后验证构建与运行效果。支持的环境:浏览器端 SDK 需添加 spanStreamingIntegration()(会自动启用 stream);服务端 SDK 需在 Sentry.init() 中添加 traceLifecycle: 'stream';框架 SDK(如 Next.js、Nuxt、SvelteKit、Remix、Astro 等)需分别迁移客户端与服务端配置。
必要用法:前提为 Sentry JavaScript SDK >=10.53.1 且已启用追踪(tracesSampleRate 或 tracesSampler)。若存在 beforeSendSpan 回调,必须用 Sentry.withStreamedSpan() 包装,否则会回退到 static 模式;回调字段随之变化:description 改为 name,data 改为 attributes,对象类型为 StreamedSpanJSON。beforeSendTransaction 在流式模式下无效,需迁移到 beforeSendSpan 或 ignoreSpans 后移除。ignoreSpans 在两种模式下均可用,但流式模式在跨度开始时求值,只能依据跨度名与创建时属性。浏览器端如需性能分析,应使用 v2 选项 browserProfilingIntegration()、profileSessionSampleRate 与 profileLifecycle,不能与旧版 profilesSampleRate 混用。
验证与限制:迁移后可用 npx tsc --noEmit 与 npm run build 检查类型和构建,并在网络面板确认跨度信封 content type 为 application/vnd.sentry.items.span.v2+json。常见问题包括未包装 withStreamedSpan 导致回退、字段类型错误、旧版分析选项失效等。当前跨度流式仅支持 JavaScript SDK,Python、Ruby、Go 及其他 SDK 暂未提供。