← 文章 / 云原生与基础设施
signoz 11天前 · 2026-11-11 06:42:18 · 11 阅读

使用 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 环境(二选一):
  • 已安装 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

核对以下配置:

使用 http/protobuf,而非 gRPC

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 并执行查询,确认数据正在到达。

Grok Build token usage metric charted in the SigNoz Metrics Explorer
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.totalmsoutcome、auth_mode
grok_code.startup.phase_durationmsphase、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' 过滤即可查看事件流。每个事件的详细信息都存放在属性而非日志正文中,需打开具体记录查看。

A Grok Build event in SigNoz showing its attributes
Grok Build 事件的详细信息通过 duration_ms、tool_call_count 和 cancellation_category 等属性承载

常用属性包括 model、input_tokens、output_tokens、cache_read_tokens、reasoning_tokens、tool_name、outcome 和 duration_ms。每个事件还携带 session.id 和 prompt.id,因此可以将处理单个 prompt 期间生成的所有数据归类在一起。

AI 可观测性

AI 可观测性 面板仅读取 traces。由于 Grok Build 发送的是 metrics 和 logs,其数据不会显示在该面板中。请使用 Grok Build 仪表盘 来查看 token 使用情况、工具活动、错误及启动延迟。

Grok Build 可观测性仪表盘

Grok Build 仪表盘 开箱即用地提供按类型和模型划分的 token 用量、工具活动、错误分类及启动延迟。

Grok Build dashboard in SigNoz
Grok Build 仪表盘模板

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 管道进行埋点监控:

查看全部 LLM 可观测性集成,为技术栈中的其他组件完成埋点。

更多资源:

原始来源: signoz

评论 (0)