Vercel News

Search trace spans from the Vercel CLI

8.5内容质量

TL;DR · AI 摘要

Vercel CLI 新增通过命令行搜索 trace spans 功能，提升调试效率。

核心要点

  • 使用 `vercel traces search` 命令可直接搜索最近一小时的 trace spans，无需进入仪表板。
  • 支持通过 --status、--since 等参数过滤错误、时间范围等，提升排查效率。
  • 结合 KQL 语法（如 `span.duration > 2000`）可精准定位性能瓶颈。

结构提纲

按章节快速跳转。

  1. §功能概述

    介绍 Vercel CLI 新增 trace spans 搜索功能的核心价值。

  2. ·基础用法

    默认返回最近一小时最多 100 个 trace spans，支持多种过滤参数。

  3. ›高级查询

    通过 KQL 语法实现基于 duration 等字段的复杂查询。

  4. ·输出格式

    --json 参数可输出结构化数据供自动化分析使用。

  5. ›使用场景

    适用于错误排查、性能优化和安全行为分析等场景。

思维导图

用一张图看清主题之间的关系。

查看大纲文本（无障碍 / 无 JS 友好）
  • Vercel CLI Trace搜索功能
    • 核心功能
      • 终端直接搜索trace spans
    • 过滤参数
      • --status/--since/--until
      • KQL语法支持
    • 输出格式
      • JSON结构化数据

金句 / Highlights

值得收藏与分享的关键句。

#Vercel#CLI#调试工具#trace分析
打开原文

从 Vercel CLI 搜索追踪跨度 - Vercel

您和您的编码代理现在可以通过 vercel traces search 命令在终端中搜索项目追踪跨度。

每个跨度代表请求中的一个步骤，帮助您在不打开仪表板的情况下调查错误、延迟和安全相关行为。

默认情况下，vercel traces search 会返回最近一小时内最多 100 个跨度，按最新排序，因此您可以直接搜索而无需先找到请求或追踪 ID。可通过环境、服务、跨度名称、状态、部署 ID、请求 ID、追踪 ID 或跨度 ID 进行过滤，或使用 --since 和 --until 缩小时间范围：

code
# 上一小时内的错误跨度
vercel traces search
--status
error
--since
1h
# 某个追踪中的所有跨度
vercel traces search --trace-id 4bf92f3577b34da6a3ce929d0e0e4736

查找最近的错误或检查某个追踪中的所有跨度。

对于没有专用选项的过滤条件，可使用 --query 和 Vercel 支持的 Kibana 查询语言（KQL）子集。它支持 duration 等字段以及跨度和资源属性：

code
# 持续时间超过两秒的跨度
vercel traces search
--query
'span.duration > 2000'

查找持续时间超过两秒的跨度。

添加 --json 可输出每个跨度的 JSON 对象，为脚本和代理提供结构化数据进行分析。

通过 vercel upgrade 更新到最新版 Vercel CLI，然后运行 vercel traces search --help 查看所有可用选项。更多内容请参阅 vercel traces 文档。