Vercel Tracing 用于为服务器代码接入 OpenTelemetry 仪表化，并查看部署流量产生的 span。核心工作流是：在框架的服务器启动钩子中注册 @vercel/otel，部署并触发一个服务器路由，再用 vercel traces 搜索并检查 trace。同一批 trace 可用于调试失败请求和衡量慢操作。使用时只阅读当前任务所需的参考文档。
用途与范围
Tracing 只覆盖实际运行服务器代码的请求：动态路由、API 路由、函数和按需渲染。静态页面、预渲染页面和 CDN 缓存命中不运行应用代码，因此 trace 既无法解释它们，也无法加速它们；这类内容应通过缓存、包体积和 Core Web Vitals 优化来处理。
主要能力
- 采集：判断哪些 span 需要应用侧配置，以及选择常开追踪、请求捕获或浏览器会话。
- 仪表化：发现框架的启动钩子、接入并验证 SDK，或使用 Sentry。
- 框架支持：Next.js 仪表化与详细 span；SvelteKit 2/3 的服务器追踪与钩子。
- 自定义 span：度量应用操作并记录失败。
- 上下文传播：跨服务连接 trace，包括出站 URL 匹配、非 fetch 客户端与队列、入站请求。
- 配置：查看或修改常开追踪的采样规则。
- 捕获：复现请求或追踪浏览器流程。
- 搜索：查找慢 span 或失败 span、选择过滤条件、解析结果。
- 检查：获取请求 trace，选择时间线、树或瀑布图视图。
- 性能：为路由、API、函数或服务端渲染页面提速，包括包裹操作、读取精确耗时、前后对比。
- 故障排查：排查空结果、查询失败、缺失 span 或属性截断。
配置流程
- 检查现有配置：框架与适配器版本、是否已注册 OpenTelemetry provider 或 Sentry v8+、框架追踪开关。应扩展已有 provider，不要注册第二个。
- 判断哪些内容需要应用侧配置。基础设施与出站 fetch 的 span 是自动的；框架 span 和自定义 span 需要 @vercel/otel。
- 安装 @vercel/otel 与 @opentelemetry/api，然后从框架已验证的服务器启动钩子中注册一次 SDK。Next.js 中即 instrumentation.ts 的 register()：
import { registerOTel } from '@vercel/otel';
export function register() { registerOTel({ serviceName: 'checkout' }); }
其他框架可参考 SvelteKit 等文档；Next.js 的详细 span 与预渲染见对应说明。Next.js 和 SvelteKit 会自动加入入站请求 trace；其他框架可能需要提取入站上下文。按需添加自定义 span 与上下文传播。 4. 构建并部署到预览或生产，触发一个由服务器执行的路由，检查其 trace。用 inspect 确认 span 名称与父子关系，用 search JSON 确认 service.name。本地 exporter 检查不能证明 Vercel 已采集。
排查与性能流程
用于调查错误和提升应用性能。优化前先测量：在部署后的 span 确认之前，不要声称已有提速。
即使代码中原因看似明显（例如顺序 await），也要测量。可在与修复相同的变更中为可疑操作添加 span，或在条件允许时先在基线部署中添加。在部署后的 trace 确认前，将预期收益表述为估算，并指出用户应对比的 span。阅读代码只能找到候选，无法显示在 Vercel 上哪个是主要瓶颈，因为数据库位置、冷启动和外部 API 会改变开销。
确认慢或失败的路由在每次请求时都运行服务器代码；静态、预渲染或缓存响应没有应用 span。核实预览或生产部署、采集模式与流量。检查应用 OpenTelemetry 配置（框架与自定义 span）以及常开追踪的采样规则。复用已完成的配置。
按受影响的项目、路由、环境和时间窗口查找慢或失败请求，或捕获一次复现。
用 startActiveSpan 将每个可疑操作（数据库查询、外部调用、缓存读取、渲染、CPU 密集工作）包裹为自定义 span，部署后从 trace 读取精确耗时，保存为基线。
检查 trace 以定位失败操作、关键路径上最慢的 span、顺序等待，以及父 span 与子 span 之间未测量的空隙；将它们对应到应用代码。为任何空隙添加 span 并再次测量。
修改已测量的原因，并保留其 span。部署后，在相似负载与采集设置下的等效请求间对比该 span 与整个请求。报告前后耗时、样本数、错误与剩余不确定性。
有限的 span 搜索不代表完整的延迟分布。渲染或交互瓶颈应结合浏览器性能分析，与 trace 一起使用。
CLI 说明
确认 vercel traces --help 列出了所需子命令。vc 与 vercel 等价。
当 CLI 检测到智能体且 stdin 非 TTY 时，默认以 --non-interactive 运行。该模式下 search 与 config 输出 JSON，search --columns 会被拒绝，生产捕获需要 --yes，config rm 返回命令供用户自行运行而不是提示。
搜索覆盖所选团队的所有项目，即使从已链接目录执行。用 --scope 指定团队，用 --project 限定单个应用的搜索。inspect 与 config 仍限于项目范围；团队搜索后，用结果中的 project 进行检索。
不要仅为调查问题而更改采样。空采样结果不能证明请求从未发生；要区分认证或 API 失败与成功的空搜索。