用途:把某个 span op 迁移为低基数(low-cardinality)span 名称,仅在启用 span streaming 时生效;traceLifecycle: 'static' 时所有 span 名称必须与之前逐字节一致。span 名称中绝不能出现原始 URL、id 或查询参数,SDK 无低基数取值时使用该 op 的静态回退名。pageload 已先行迁移,可作为参考实现。
主要能力与规则:在每个命名点内联使用 hasSpanStreamingEnabled(client) 做门控,不集中门控;在 span 开始时设置低基数名称,并在之后所有可能写入高基数名称的位置同样处理,禁止事后重写名称;只改名称,不动 sentry.source、url.template、http.route 等属性;不通过属性推导名称,复用站点已有的 url.template / http.route 值;不引入辅助函数或抽象,每个站点用内联三元表达式,回退字符串常量从 packages/core/src/tracing/spans/spanNames.ts 导出;回退名不得进入 scope.setTransactionName;sentry.segment.name 必须与 segment span 名称一致。
使用方式:输入必填的 <span-op>(如 navigation、db.query、http.client),可选 [constraints] 限定范围;缺失 op 时应询问而非猜测。先查阅 Sentry 命名约定确定回退名,再用 grep 穷举所有命名站点与后续名称写入点,修复读取 span 名称并与路径比较的代码(改读 url.path 等属性),保护 setTransactionName,保持 sentry.segment.name 一致。
验证与限制:需先构建(如 yarn build:dev:filter @sentry/browser),运行 vitest 与 Playwright 集成测试,最后执行 yarn format 和 yarn lint,并在 MIGRATION.md 的“Span name changes”表格中补充一行。已否决的做法包括:在捕获/序列化时重写名称、使用 updateRouteSpanName 辅助函数、通过通用约定解析器从 url.template 推导名称、在 scope 上跟踪第二个 segmentName。具体命令与代码示例以原始资料为准。