使用 OpenTelemetry 实现 Grok 构建的可观测性与监控
Grok Build 是 xAI 推出的终端编码 Agent。它自带 OpenTelemetry exporter,接入只需要改配置:无需安装额外的库,也不用运行 collector。启用后,它会输出覆盖 token 用量、对话轮次、工具调用、错误和启动耗时等指标,并为每个会话发送结构化事件流。
在 SigNoz 中获得完整的 Grok Build 可观测性后,你可以看到团队花了多少 token、用在了哪些模型上,Agent 实际调用了哪些工具,对话轮次失败的频率和原因,以及启动时间都花在了哪里。
Grok Build 输出的是指标和事件,而非 trace
与本节的大多数集成不同,Grok Build 没有 trace exporter。所有数据都以指标形式到达 ai.xai.grok_code meter scope 下,外加 OTLP 日志记录。由于没有可查看的 trace 瀑布图,仪表盘就是主要视图。
前置条件
- SigNoz 环境(二选一):
- 拥有有效 ingestion key 的 SigNoz Cloud 账户
- 自托管的 SigNoz 实例
- 已安装 Grok Build。参见 xAI 安装指南
- SuperGrok 订阅,或配置
XAI_API_KEY
用 OpenTelemetry 监控 Grok Build
Grok Build 的遥测需要双重开启:GROK_EXTERNAL_OTEL 总开关和至少一个 exporter 都必须设置,只设其一不会输出任何数据。
步骤 1:以启用遥测的方式启动 Grok Build
复制以下命令:
export GROK_EXTERNAL_OTEL=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export OTEL_METRIC_EXPORT_INTERVAL=10000
grok
核对以下配置:
<region>:你的 SigNoz Cloud 所在区域。<your-ingestion-key>:你的 SigNoz ingestion key。
Grok Build 1.0.3 虽然将 gRPC 列为支持的协议,但选择它会在导出阶段失败,并报出 gRPC protocol is not compatible with HTTP transport 错误。此时遥测流仍显示自身为活跃状态,终端没有任何输出,这种静默故障导致数据无法到达 SigNoz。若未收到数据,请运行 grok --debug 并检查 external otel: 相关的行。
Grok Build 的配置文件中刻意没有 headers 键位,确保凭据不写入磁盘。所有非机密设置都可以作为 otel_* 键位存放在 ~/.grok/config.toml 的 [telemetry] 下,但摄取密钥必须来自 OTEL_EXPORTER_OTLP_HEADERS。
步骤 2:生成一些遥测数据
运行几个提示词,让智能体执行读文件或运行命令等操作,以便工具指标和 Token 指标有所报告。
复制grok -p "List the files in this directory and summarise what this project does."
默认的指标导出间隔为 60 秒,因此上述代码片段将其降低至 10 秒,以便你验证管道。事件默认为每 5 秒导出一次。
使用自托管 SigNoz?大多数步骤相同。若要适配本指南,请参照 Cloud → Self-Hosted 章节更新端点并移除摄取密钥请求头。
在 SigNoz 中查看 Grok Build 指标
指标是 Grok Build 的核心信号。打开 Metrics Explorer,搜索 grok_code.token.usage 并执行查询,确认数据正在到达。

所有指标都位于 ai.xai.grok_code 度量作用域下。由于所有计数器均为单调增量总和,请使用 increase 进行聚合以获取总计,而不是使用 rate。
| 指标 | 单位 | 关键属性 |
|---|---|---|
grok_code.session.count
| {session} | 仅基础属性 |
grok_code.turn.count | {turn} | outcome(completed、cancelled、error)、model |
grok_code.token.usage | {token} | type(input、output、reasoning、cache_read)、model |
grok_code.tool.usage | {call} | tool_name、outcome |
grok_code.tool.decision | {decision} | tool_name、decision、access_kind、permission_mode |
grok_code.error.count | {error} | error_category、model |
grok_code.startup.total | ms | outcome、auth_mode |
grok_code.startup.phase_duration | ms | phase、outcome、auth_mode |
指标默认会附带 session.id,大规模部署时会产生大量时间序列,可设置 OTEL_METRICS_INCLUDE_SESSION_ID=false 将其去掉。OTEL_METRICS_INCLUDE_ACCOUNT_UUID 的用法相同;OTEL_METRICS_INCLUDE_VERSION 和 OTEL_METRICS_INCLUDE_ENTRYPOINT 默认关闭,可按需开启。
在 SigNoz 中查看 Grok Build 日志
打开 Logs Explorer,用 service.name = 'grok-cli' 过滤即可查看事件流。每个事件的详细信息都存放在属性而非日志正文中,需打开具体记录查看。

常用属性包括 model、input_tokens、output_tokens、cache_read_tokens、reasoning_tokens、tool_name、outcome 和 duration_ms。每个事件还携带 session.id 和 prompt.id,因此可以将处理单个 prompt 期间生成的所有数据归类在一起。
AI 可观测性 面板仅读取 traces。由于 Grok Build 发送的是 metrics 和 logs,其数据不会显示在该面板中。请使用 Grok Build 仪表盘 来查看 token 使用情况、工具活动、错误及启动延迟。
Grok Build 可观测性仪表盘
Grok Build 仪表盘 开箱即用地提供按类型和模型划分的 token 用量、工具活动、错误分类及启动延迟。

Grok Build 可观测性故障排查
SigNoz 中没有数据
检查是否同时设置了 GROK_EXTERNAL_OTEL=1 和至少一个 exporter。单独设置其中任意一个都不会产生输出。随后运行 grok --debug,并在 ~/.grok/debug/ 下的日志中搜索包含 external otel: 的行,这些行会报告流是否已解析配置以及导出是否成功。
指标缺失但事件已到达
这两种信号的导出间隔不同。Metrics 默认间隔为 60 秒,而 events 默认为 5 秒,因此在启动后的一分钟内,metrics 可能看起来像是缺失的。在验证期间,请将 OTEL_METRIC_EXPORT_INTERVAL 设置为 10000。
最初几秒内没有数据到达
Grok Build 在启动时会暂缓发送遥测数据,直到从 xAI 拉取到全局策略为止,因为该策略可能会禁用数据流。等待时间有上限,最迟 30 秒内必定开始发送。
导出错误提示 gRPC 相关
设置 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf。文档中虽标注支持 gRPC,但在 1.0.3 版本中实际无法使用。
相关集成
如果还在使用其他 AI 编程代理,可以用同一套 OpenTelemetry 管道进行埋点监控:
- 用 OpenTelemetry 监控 OpenAI Codex - 追踪 Codex CLI 会话、token 消耗及命令级调用链
- 用 OpenTelemetry 监控 Claude Code - 追踪 token 用量、成本和工具调用决策
- 用 OpenTelemetry 观察 OpenCode - 追踪 OpenCode 会话、工具调用及每条消息的成本
查看全部 LLM 可观测性集成,为技术栈中的其他组件完成埋点。
更多资源: