将 agent 自身的遥测数据发送到 sigiro

Claude Code 和 Codex 都会发出关于自身会话的 OpenTelemetry 数据。将它们指向 sigiro，即可用 SQL 读取 token 数量、工具调用和会话延迟。

本指南介绍如何记录 agent 的行为，而不是你的服务的行为。Claude Code 和 Codex 都会发出关于自身会话的 OpenTelemetry 数据。将这些遥测数据指向 sigiro，会话就会变成可供查询的数据行。

这与用 agent 为你的代码埋点是两项不同的任务，后者是把 你的服务 指向 sigiro。如果两者都需要，就都做一遍。

开始之前

你需要一台 sigiro 服务器。用 sigiro serve 启动，或使用快速上手中的 Docker 命令启动。

在下面的配置中，两个 agent 都通过 OTLP gRPC 从 4317 端口导出数据。自托管服务器不需要密钥。

Claude Code

Claude Code 从环境变量中读取遥测配置。请在启动 Claude Code 的环境中设置这些变量。可以使用 shell 配置文件、.envrc 文件或包装脚本：

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

如果使用托管服务，请额外添加 OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${SIGIRO_API_KEY}"。切勿将密钥提交到任何文件中。

Codex

Codex 从自己的配置文件读取遥测配置，而不是从环境变量读取。请编辑 ~/.codex/config.toml：

[otel]
environment = "dev"
log_user_prompt = false
exporter = "otlp-grpc"

[otel.exporter."otlp-grpc"]
endpoint = "http://localhost:4317"

如果使用托管服务，请额外添加 headers = { authorization = "Bearer ${SIGIRO_API_KEY}" }。并在启动 Codex 的环境中设置 SIGIRO_API_KEY。

两者共有的一个限制

以上配置只覆盖 agent 进程本身，不覆盖 agent 运行的命令。agent 通过其 shell 工具启动的应用程序并不总能继承这些变量，因此已埋点的服务仍需要自己的导出器配置。这种情况请参阅用 agent 为你的代码埋点。

确认配置生效

启动 agent，运行一次提示词，然后查询 sigiro 收到了哪些服务：

curl http://localhost:9999/v1/services

agent 会把自己上报为一个服务。等它出现之后，再查询会话：

curl -X POST http://localhost:9999/v1/query \
  --data "SELECT service_name, span_name, count(*) AS n
          FROM sigiro_spans
          WHERE timestamp > now() - INTERVAL '1 hour'
          GROUP BY 1, 2 ORDER BY n DESC"

agent 还会上报计数器和仪表值，这些数据会落到 sigiro_metrics_* 系列表中，而不是 sigiro_spans 表。关于这些表说明了各系列表分别存放什么数据，以及每个系列描述的是哪一台机器。

下一步

用 agent 为你的代码埋点 —— 把你的服务也指向 sigiro
CLI 参考 —— 全部子命令和参数