AI Coding Agent 的 OpenTelemetry 本機可觀測性研究報告

摘要

本研究以 Docker 於本機部署一套 LGTM（Loki、Grafana、Tempo、Mimir）可觀測性後端，收集並分析 Claude Code、Codex 與 GitHub Copilot CLI 等 AI 程式設計代理（AI coding agent）與大語言模型互動時所產生的遙測資料（telemetry），並在 Grafana 中觀測請求次數、token 用量、快取使用、實際成本（USD）與 AI Credits。

研究結果顯示，三款主要代理工具皆具備原生 OpenTelemetry 匯出能力，但訊號類型、欄位完整性與成本單位存在顯著差異：Claude Code 原生輸出 logs/metrics 且含 USD 成本；Codex 原生輸出 logs，可經正規化轉為 Prometheus metrics，但不含直接 USD 成本；GitHub Copilot CLI 原生輸出 traces，可經正規化轉為 metrics 與可搜尋之 Loki logs，成本以 AI Credits 呈現。Antigravity CLI 則尚無可用之原生 OTel/OTLP 匯出路徑。

研究背景與動機

隨著 AI 程式設計代理日益普及，開發者日益需要了解不同工具在大語言模型互動時消耗了多少 token、成本落在何處，以及不同使用策略是否會造成成本差異。然而，各工具的遙測能力參差不齊，若在沒有實證基礎的情況下討論多工具整合，容易低估各工具間的遙測能力差異，也可能過早投入自製 proxy 或 log parser。

OpenTelemetry（OTel）作為跨語言、跨平台的遙測管線標準，提供 metrics、logs、traces 三類訊號的統一匯出與接收機制，是建立可重複驗證之遙測基線的合適基礎。本研究選擇以本機單一 Docker 後端為起點，先驗證 OTel 串接方式，再逐步擴充至多工具比較，以避免一開始即維護多個 observability 容器。

研究目標

1. 驗證 AI 程式設計代理能否透過原生 OpenTelemetry 將 token、成本、API 請求與工具活動等遙測匯出至本機後端。
2. 建立一套可重複執行的本機 LGTM 可觀測性後端，作為跨工具比較的統一接收端。
3. 比較各代理工具的訊號類型、欄位完整性、成本可見度與隱私風險。
4. 將不同工具的原始欄位映射至 OpenTelemetry GenAI semantic conventions 之正規化欄位，使統合儀表板得以跨工具比較。

研究方法

觀測後端架構

本研究採用 Grafana 官方 grafana/otel-lgtm 單一 Docker image 作為本機 all-in-one 後端，內含：

• OpenTelemetry Collector
• Grafana
• Loki（logs）
• Mimir（metrics）
• Tempo（traces）

該 image 定位為 self-managed development、demo、testing 用途，符合本研究之本機驗證目標。此外另部署一個 agent-otel-normalizer sidecar，負責將不同訊號來源（Loki logs、Tempo traces）轉換為 canonical Prometheus metrics，並以 SQLite 記錄已處理之事件／span id，避免容器重啟後重複累加。

各代理工具設定方式

• Claude Code：透過環境變數啟用 OTel，以 OTLP gRPC 4317 匯出 metrics 與 logs。
• Codex：透過 user-level ~/.codex/config.toml 的 [otel] 區段或單次 -c override，以 OTLP HTTP/protobuf 4318 匯出 logs。
• GitHub Copilot CLI：透過環境變數啟用 OTel，以 OTLP HTTP/protobuf 4318 匯出 traces 與 metrics，並可選擇是否捕捉 prompt／response／tool 內容。

詳細設定請見附錄〈操作步驟〉。

正規化與欄位映射

本機 OpenTelemetry Collector 透過 transform processor 將各代理工具的原始 metadata 映射為 OTel GenAI semantic conventions 風格的 canonical 欄位，例如：

• Claude Code service.name=claude-code → agent.name=claude-code
• Codex service.name=Codex Desktop／codex_exec／codex_cli_rs → agent.name=codex
• GitHub Copilot CLI service.name=github-copilot → agent.name=github-copilot
• Claude Code input_tokens／Codex input_token_count → gen_ai.usage.input_tokens
• Claude Code cost_usd → agent.cost.usd.actual

研究結果

Claude Code

Claude Code 官方文件明確支援 OpenTelemetry，可匯出 usage、cost、tool activity。已驗證：

• 以 OTLP gRPC 成功匯出 metrics 與 logs 至本機後端。
• API request event 包含 model、cost_usd、input_tokens、output_tokens、cache_read_tokens、cache_creation_tokens、request_id、query_source 等關鍵欄位。
• 成本以實際 USD（cost_usd）呈現，可直接做 session 或 model 維度之成本分析。

Codex

Codex 官方文件支援 OTel log export，需於 [otel] 區段啟用。已驗證：

• 以 OTLP HTTP/protobuf 成功匯出 logs 至本機後端，經 normalizer 轉為 canonical Prometheus metrics。
• 代表性事件包含 codex.conversation_starts、codex.api_request、codex.sse_event、codex.tool_decision、codex.tool_result。
• SSE response.completed 帶 token counts；但官方不保證直接輸出 USD 成本，需另以 pricing 表或 Enterprise Analytics API 換算。
• user prompt 預設 redacted，需明確設定 log_user_prompt = true 才會送出 prompt 內容。

GitHub Copilot CLI

GitHub Copilot CLI 具備原生 OTel 支援，遵循 OTel GenAI semantic conventions。已驗證（本機 copilot 1.0.63）：

• 主要送 traces（進 Tempo）與 metrics（進 Prometheus/Mimir），不直接送 Loki logs。
• Normalizer 自 Tempo trace 中每個 gen_ai.operation.name=chat span 讀取 token，並以 github.copilot.nano_aiu / 1e9 換算 CLI 顯示之 AI Credits，輸出 canonical metrics。
• Normalizer 另將 Copilot Tempo spans 派生為可搜尋之 Loki logs（copilot.chat、copilot.tool_call），使統合儀表板可像 Claude/Codex 一樣搜尋內容。
• 預設不捕捉 prompt／response／tool args 本文，需設定 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true 才會捕捉。

Antigravity CLI

截至本機測試之 agy 1.0.9，Antigravity CLI 可用 --print 做非互動式 smoke test，但尚無驗證到可用之原生 OpenTelemetry／OTLP 匯出路徑。標準 OTEL_EXPORTER_OTLP_* 環境變數測試後，LGTM stack 未收到任何 logs/metrics/traces。本研究將其列為研究中，暫不納入統合儀表板之已支援代理清單。

跨工具比較

討論

1. OpenTelemetry 是遙測管線標準，而非成本系統本身。 能觀測哪些 token/cost 欄位，取決於各工具是否將這些欄位送出。Claude Code 已涵蓋核心成本欄位，其他工具則不保證同等完整性。
2. 訊號類型差異需以正規化層彌補。 Claude/Codex 以 logs 為主，Copilot 以 traces 為主，本研究透過 normalizer sidecar 將異質訊號轉為統一 canonical metrics，方能跨工具比較。
3. 成本單位不一致需分開呈現。 Claude Code 為 USD，Copilot 為 AI Credits，兩者非同一單位，儀表板應分開顯示 agent_cost_total{currency="USD"} 與 agent_ai_credits_total。
4. 隱私風險需審慎管控。 prompt、tool payload 可能含敏感資料，本研究預設採隱私保守設定，不開啟 raw body 或 prompt logging，除非於完全本機環境且明確需求。
5. Antigravity CLI 之限制。 不應以 fragile local log parsing 作為正式觀測基礎，建議持續追蹤官方是否新增可設定的 OTLP 支援。

結論與未來方向

本研究驗證了 AI 程式設計代理透過原生 OpenTelemetry 匯出遙測至本機後端之可行性，並建立了一套可重複執行的本機 LGTM 可觀測性後端與跨工具正規化機制。Claude Code、Codex 與 GitHub Copilot CLI 三款工具皆已成功接入統合儀表板，可觀測請求次數、token 用量、成本與工具活動。

未來擴充方向：

1. 將各工具欄位映射至更完整的共同欄位矩陣。
2. 研究 Codex 成本之 pricing mapping 或 Enterprise Analytics API。
3. 持續追蹤 Antigravity CLI 之 OTel 支援進展。
4. 評估將本機架構擴展為 team deployment、雲端部署、長期 retention 與告警之可行性。
5. 精準支援任意週／月時間區間之 range query，需將 SQLite records 轉為可查時間範圍之 metrics。

附錄：操作步驟

啟動後端

docker compose up -d

Grafana：http://localhost:3000，預設帳密 admin / admin。

OTLP endpoints：

gRPC:          http://localhost:4317
HTTP/protobuf: http://localhost:4318

主要儀表板：http://localhost:3000/d/agent-otel-overview/agent-otel-overview

啟動 Claude Code

Claude Code 用 OTLP gRPC 4317。如果想每次 shell 都自動帶入，可把這些 export 加到你的 shell 設定檔，例如 ~/.zshrc；如果只想測一次，就直接貼在目前 terminal。

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_SERVICE_NAME=claude-code
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=local,service.namespace=ai-coding-tools

然後啟動：

claude

啟動 Codex

Codex CLI 目前用 HTTP/protobuf logs endpoint。Codex 的 OTel 設定建議寫進 user-level config：

mkdir -p ~/.codex
$EDITOR ~/.codex/config.toml

加入：

[otel]
environment = "local-poc"
log_user_prompt = false
exporter = { otlp-http = { endpoint = "http://localhost:4318/v1/logs", protocol = "binary" } }

不要放在 project .codex/config.toml。Codex 官方 manual 說 project-scoped .codex/config.toml 會忽略 otel 這類 telemetry 設定；要放 ~/.codex/config.toml，或用下面的 -c 單次 override。

互動式 Codex：

codex

一次性 smoke test：

codex --skip-git-repo-check --ephemeral --json --sandbox read-only \
  -C /Users/doggy8088/Documents/otel-research \
  'Reply with exactly: codex otel smoke'

如果不想改 ~/.codex/config.toml，也可以只對單次指令加 -c：

codex \
  -C /Users/doggy8088/Documents/otel-research \
  -c 'otel.environment="local-poc"' \
  -c 'otel.log_user_prompt=false' \
  -c 'otel.exporter={ otlp-http = { endpoint = "http://localhost:4318/v1/logs", protocol = "binary" } }'

啟動 GitHub Copilot CLI

Copilot CLI 用 OTLP HTTP/protobuf。若要讓儀表板可搜尋 prompt、response、tool args/result，需開啟 content capture：

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_SERVICE_NAME=github-copilot
export COPILOT_OTEL_SOURCE_NAME=github.copilot
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true

如果不想保存完整 prompt / output / tool payload，把最後一個改成：

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false

然後啟動：

copilot

驗證資料

打開統合儀表板：http://localhost:3000/d/agent-otel-overview/agent-otel-overview

常用 filter：

• Agent：claude-code、codex、github-copilot。
• Model：依實際收到的 telemetry model label 篩選。
• Event：看 raw/derived event，例如 codex.sse_event、copilot.chat。
• Content regex：搜尋 Copilot derived logs 的 prompt/output/tool payload。
• Trend bucket：切換趨勢聚合粒度，例如 5m、1h、1d、1w、30d。

目前儀表板會顯示：

• 模型回應完成次數。
• input / output tokens。
• cache read / cache creation / reasoning / tool tokens。
• Claude Code 實際 USD cost。
• Copilot AI Credits。
• Copilot searchable events table。

停止與重設

停止但保留資料：

docker compose down

重設所有本機 telemetry 資料：

docker compose down -v --remove-orphans

down -v 會刪掉 LGTM 資料 volume 與 normalizer SQLite state；下次 docker compose up -d 會從空資料重新開始。

參考文獻

• Claude Code Monitoring: https://code.claude.com/docs/en/monitoring-usage
• Grafana Docker OpenTelemetry LGTM: https://grafana.com/docs/opentelemetry/docker-lgtm/
• OpenTelemetry Collector: https://opentelemetry.io/docs/collector/
• OpenTelemetry GenAI attributes registry: https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
• OpenAI Codex advanced configuration: https://developers.openai.com/codex/config-advanced
• GitHub Copilot CLI command reference: https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference

相關文件

• 操作手冊：docs/operations/claude-code-otel-poc.md
• Claude Code 研究筆記：docs/research/claude-code-otel-research.md
• Codex 研究筆記：docs/research/codex-otel-research.md
• Copilot CLI 研究筆記：docs/research/copilot-cli-otel-research.md
• Antigravity CLI 研究筆記：docs/research/antigravity-otel-research.md