从 Vercel CLI 搜索追踪跨度
内容提要
Vercel CLI 新增 traces search 命令，开发者与编码代理可直接在终端搜索项目追踪跨度，无需打开仪表盘。默认返回最近一小时最多100条跨度，支持按环境、服务、状态、部署ID等过滤，或用 --since/--until 限定时间，并支持 KQL 查询（如筛选超过两秒的跨度），可用 --json 输出结构化数据供脚本分析。
延伸解读
终端直接搜索追踪跨度，提升排查效率
Vercel CLI 新增的 traces search 命令允许开发者和编码代理直接在终端搜索项目的追踪跨度，无需打开仪表盘。默认返回最近一小时最多100条跨度，按时间倒序排列，方便快速定位错误、延迟或安全相关问题。这减少了在仪表盘和终端之间切换的步骤，尤其适合习惯命令行工作流的用户。
灵活过滤与时间范围控制
该命令支持按环境、服务、跨度名称、状态、部署ID、请求ID、追踪ID或跨度ID进行过滤，并可通过 --since 和 --until 参数缩小时间范围。例如，使用 --status error --since 1h 可查找最近一小时的错误跨度。对于没有专用选项的过滤条件，可以使用 --query 参数配合 KQL 查询语言，如筛选持续时间超过两秒的跨度。
结构化输出便于脚本与代理分析
添加 --json 标志后，命令会为每个跨度输出一个 JSON 对象，提供结构化数据供脚本或编码代理进一步分析。这使得自动化监控、日志处理或智能代理集成成为可能，无需人工解析文本输出。开发者可以结合其他工具对结果进行聚合、告警或可视化。
Q&A
Vercel CLI 的 traces search 命令是什么？
vercel traces search 是 Vercel CLI 新增的命令，允许开发者和编码代理直接在终端搜索项目的追踪跨度（trace spans），无需打开仪表盘。每个跨度代表请求中的一个步骤，有助于调查错误、延迟和安全相关行为。
vercel traces search 默认返回什么结果？
默认情况下，vercel traces search 返回最近一小时最多 100 条跨度，按最新优先排序，因此无需先找到请求或追踪 ID 即可搜索。
如何使用 vercel traces search 按条件过滤结果？
可以通过环境、服务、跨度名称、状态、部署 ID、请求 ID、追踪 ID 或跨度 ID 来过滤结果，也可以使用 --since 和 --until 缩小时间范围。例如：vercel traces search --status error --since 1h 查找最近一小时的错误跨度。
vercel traces search 支持 KQL 查询吗？怎么用？
支持。对于没有专用选项的过滤器，可以使用 --query 参数配合 Vercel 支持的 Kibana 查询语言（KQL）子集。它支持 duration 等字段以及跨度和资源属性。例如：vercel traces search --query 'span.duration > 2000' 查找耗时超过两秒的跨度。
如何让 vercel traces search 输出 JSON 格式？
添加 --json 标志即可输出每个跨度一个 JSON 对象，为脚本和代理提供结构化数据进行分析。
如何更新 Vercel CLI 以使用 traces search 命令？
使用 vercel upgrade 更新到最新版 Vercel CLI，然后运行 vercel traces search --help 查看所有可用选项。更多信息请参阅 Vercel traces 文档。
