Vercel Tracing正式可用：支持KQL搜索与CLI

Vercel 的可观测性能力补上了一块关键拼图。Vercel Tracing 已从 beta 阶段转入正式可用（GA），面向所有套餐开放。此次更新的重点不只是"转正"，而是把追踪数据的检索、保留和默认启用方式都做了一轮实质性升级。

从"按请求查看"到"全局检索"

beta 阶段的使用方式相当受限：你只能在日志页面里按单个请求打开对应的 trace，缺少一个能纵观全局的入口。现在 Vercel 新增了独立的 Traces 页面，把项目乃至整个团队的所有 trace 与 span 集中呈现。

页面支持在 Spans 列表和 Traces 列表之间切换，两者都可以单独过滤。检索使用 Kibana Query Language（KQL），例如 span.name:db* AND span.duration > 500 这样的查询，可以按名称和耗时同时收窄，直接定位到慢速的数据库 span。此外还提供了 Live 模式，新产生的 trace 会实时流入视图，适合在压测或线上排障时盯着看。

对习惯了日志检索的团队来说，KQL 的引入降低了上手成本——这套语法在可观测性工具链里已经相当通用，不需要为 Vercel 单独学习一套查询语言。

KQL（Kibana Query Language） 是 Elastic 生态中用于检索日志与可观测性数据的查询语法，采用 field:value 的键值对形式，并支持 AND、OR、NOT 逻辑组合、通配符（如 db*）以及数值比较（如 span.duration > 500）。它的设计目标是在不牺牲表达力的前提下保持易读，因此被大量日志与 APM 平台采纳为通用检索语言。对团队而言，使用 KQL 意味着查询语句可以在不同工具之间迁移复用，也便于把常见排查模式固化成文档或脚本。需要注意的是，KQL 各实现之间存在细微差异，字段命名尤其依赖具体的数据模型，因此跨平台复用查询时仍需核对字段名。

Trace 与 Span 是分布式追踪中的两个基本概念。一次完整的请求处理过程称为一个 trace，由 trace ID 唯一标识；trace 内部被拆分为若干 span，每个 span 代表一个具体的操作单元，例如一次数据库查询、一次外部 HTTP 调用或一个框架中间件阶段。span 之间通过父子关系构成调用树，从而还原请求在各服务间的流转路径与耗时分布。检索时按 span 过滤（如筛选耗时超过阈值的数据库 span），再回溯到其所属 trace，是定位性能瓶颈的典型手法。这也是 Traces 页面同时提供 Spans 列表与 Traces 列表两种视图的原因：前者用于找"慢操作"，后者用于看"整条链路"。

CLI 与仪表盘共用同一套查询语法

这次更新里比较实用的一点，是 CLI 和仪表盘使用完全相同的 KQL。在仪表盘里拼好的查询，可以原封不动地放进 vercel traces search --query 执行，不需要做任何转写。

CLI 的检索范围默认覆盖团队内所有项目，也可以通过 --project 锁定单个项目。除了搜索，CLI 还提供了另外两个子命令：vercel traces inspect <request-id> 用于深入查看单条 trace，vercel traces config 用于管理项目的采样规则。原文给出的示例很直观：先用 vercel traces search --query 'span.duration > 2000' 找出耗时超过两秒的 span，再用 vercel traces search --status error --since 1h 拉出最近一小时的所有错误。

把排障动作脚本化，意味着这类查询可以接进 CI、告警脚本或日常巡检流程，而不是只能靠人在浏览器里点击。

新项目默认开启追踪

beta 时期有一个明显的摩擦点：如果不手动添加采样规则，系统不会收集任何数据。正式版改变了这一默认行为。

从 Next.js 16.5 开始，在 Vercel 上新建的、至少包含一个 Node.js 函数的项目，会在首次成功构建后自动开启追踪。Vercel 会添加一条覆盖所有环境、采样率 100% 的规则，并在构建时注入 instrumentation，因此 trace 里会自带 Next.js 框架层面的 span，无需任何配置。如果不想开启，在 Settings → Tracing 中删除所有采样规则即可。

这个默认值对多数团队是合理的：新项目通常在早期就需要可观测性，而 100% 采样在低流量阶段成本可控。但对高流量项目来说，后续大概率仍需主动调整采样率。

采样率（sampling rate） 指在产生的全部请求中，实际被记录为 trace 的比例。100% 采样意味着每个请求都被完整追踪，数据最完整，但存储与计费开销随流量线性增长；降低采样率（如 10%）可显著压缩成本，代价是低频或间歇性问题可能落在未被采样的请求上而无法观测。常见的折中做法是头部采样（在请求入口按固定比例决定）与尾部采样（先收集再按错误或延迟条件保留）。Vercel 为新项目默认设置 100% 采样，是基于低流量阶段成本可控的判断；高流量项目则应结合自身 QPS 与保留期评估开销，再调整规则。

instrumentation 在此语境下指自动注入的追踪埋点代码。Vercel 在构建阶段向项目注入 instrumentation，使运行时能够自动创建 span 并上报，无需开发者手动引入 SDK 或在每个函数中埋点。对 Next.js 项目而言，这类注入还能覆盖框架层面的生命周期（如路由处理、服务端渲染、数据获取），使 trace 中天然带有框架级 span，从而把"应用代码耗时"与"框架开销"区分开。这也是自动追踪附带运行时条件的原因：注入机制依赖特定的框架版本与 Node.js 运行时环境，纯边缘运行时或非 Next.js 项目不在其覆盖范围内。

保留期大幅延长

beta 阶段 trace 的保留时间跟随运行时日志，实际窗口很短。正式版的保留策略按套餐区分：Hobby 从 1 小时延长到 3 天，Pro 从 1 天延长到 14 天，Enterprise 从 3 天延长到 14 天。

保留期从小时级跨到天级，改变的是使用场景——Trace 不再只是"出事了立刻看"的实时工具，而可以用于事后回溯、周期性性能对比，以及定位那些间歇性出现、需要翻几天数据才能对上号的问题。

价格方面，Vercel 明确表示与 beta 阶段保持一致，没有因为 GA 而调整计费。

值得关注的几点

自动追踪的默认开启附带了版本与运行时条件（Next.js 16.5、至少一个 Node.js 函数），非 Next.js 项目或纯边缘运行时的项目仍需自行配置采样规则。KQL 的检索能力很强，但也意味着团队需要约定查询习惯，否则不同人写出的查询难以复用。至于 100% 采样的默认规则在高流量项目上的实际开销，还需要结合各自的用量观察。

总体来看，这次 GA 把 Vercel Tracing 从一个"能用"的附加功能，推向了可以承载日常排障流程的基础设施：统一的查询语言、可脚本化的 CLI、默认开启的采集，以及以天计的保留窗口，四者组合起来才算完整。