エージェント自身のテレメトリーを sigiro に送信する

Claude Code と Codex は自身のセッションの OpenTelemetry を出力します。sigiro に向ければ、トークン数やツール呼び出し、レイテンシーを SQL で読み出せます。

このガイドでは、サービスの動作ではなく、エージェント自身の動作を記録する方法を説明します。Claude Code と Codex はどちらも、自身のセッションに関する OpenTelemetry を出力します。そのテレメトリーを sigiro に向けると、セッションがクエリ可能な行になります。

これはエージェントでコードを計装するとは別の作業です。あちらは あなたのサービス を sigiro に向けるものです。両方が必要であれば、両方を実施してください。

始める前に

sigiro サーバーが必要です。sigiro serve で起動するか、クイックスタートにある Docker コマンドで起動してください。

以下の設定では、どちらのエージェントもポート 4317 の OTLP gRPC 経由でエクスポートします。セルフホストのサーバーではキーは不要です。

ホスト版を使う場合、新規ユーザーは sigiro signup --name "Your Name" --email you@example.com、既存アカウントは sigiro auth login を実行してください。

ホスティングサービスでは、代わりに HTTP 経由の OTLP を使用してください。ホスティング事業者が必ずしも gRPC ポートを公開しているとは限らないため、先にホスティング版 sigiro にテレメトリーを送信するをお読みください。以下の各セクションの末尾には、ホスティング版向けの設定を記載しています。

Claude Code

Claude Code はテレメトリー設定を環境変数から読み取ります。Claude Code を起動する環境で、次の変数を設定してください。シェルのプロファイル、.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

ホスティングサービスを利用する場合は、キーを追加するだけでなく、プロトコルとエンドポイントも変更してください。api.sigiro.com は 443 でのみ応答するため、そこに :4317 や :4318 のエンドポイントを指定すると接続に失敗し、エージェントは何も報告しません。

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=https://api.sigiro.com
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer ${SIGIRO_ACCESS_TOKEN}"

キーはコミット対象のファイルに一切含めないようにします。使用するエンドポイントとポートはホスティング事業者から案内されるため、そのホストが api.sigiro.com でない場合は https://<your-sigiro-host> を使用してください。

デフォルトでは、失敗したツールは TelemetrySafeError や ShellError のような一般的なステータスしか報告しないことがあります。失敗の理由をデバッグ中に確認するには、詳細を明示的に有効にします。

export OTEL_LOG_TOOL_DETAILS=1

この設定を有効にすると、コマンド、ファイルパス、エラーテキストが送信される可能性があります。追加のプライバシー上のリスクを許容できる場合にだけ有効にしてください。

Codex

Codex はテレメトリー設定を環境変数からではなく、独自の設定ファイルから読み取ります。~/.codex/config.toml を編集してください。

[otel]
environment = "dev"
log_user_prompt = false

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

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

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

Codex はシグナルごとに 1 つのエクスポーターを指定し、exporter はログ用のエクスポーターのみを指します。trace_exporter を設定しないとスパンが得られず、metrics_exporter を設定しないとメトリクスが得られません。どちらの誤りも警告なく発生します。

ホスティングサービスを利用する場合は、HTTP エクスポーターを使用し、各エンドポイントに シグナルごとの完全なパス を指定してください。Codex は記載された URL にそのまま送信し、何も付加しないため、ベース URL では誤ったルートに届き、sigiro に拒否されます。

[otel]
environment = "dev"
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "https://api.sigiro.com/v1/traces"
protocol = "binary"
headers = { authorization = "Bearer ${SIGIRO_ACCESS_TOKEN}" }

[otel.metrics_exporter.otlp-http]
endpoint = "https://api.sigiro.com/v1/metrics"
protocol = "binary"
headers = { authorization = "Bearer ${SIGIRO_ACCESS_TOKEN}" }

[otel.exporter.otlp-http]
endpoint = "https://api.sigiro.com/v1/logs"
protocol = "binary"
headers = { authorization = "Bearer ${SIGIRO_ACCESS_TOKEN}" }

otlp-http では protocol が必須で、binary または json を指定します。SIGIRO_ACCESS_TOKEN は Codex を起動する環境で設定します。

Codex は自身を codex ではなく codex_exec として報告するため、以下の確認手順ではその名前を探してください。

両者に共通する 1 つの制限

これらの設定が対象とするのは、エージェントのプロセスのみです。エージェントが実行するコマンドは対象外です。エージェントがシェルツール経由で起動したアプリケーションが、必ずしもこれらの変数を継承するとは限りません。そのため、計装済みのサービスには、そのサービス自身のエクスポーター設定が別途必要です。それにはエージェントでコードを計装するを利用してください。

動作を確認する

エージェントを起動し、プロンプトを 1 回実行してから、sigiro が受信したサービスを確認します。

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

エージェントは自身を 1 つのサービスとして報告します。表示されたら、セッションをクエリします。

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"

エージェントはカウンターやゲージも報告します。これらは sigiro_spans ではなく sigiro_metrics_* テーブルに格納されます。どのファミリーが何を保持し、それぞれのファミリーがどのマシンを表しているかについては、テーブルについてを参照してください。

次のステップ

エージェントでコードを計装する — あなたのサービスも sigiro に向ける
CLI リファレンス — すべてのサブコマンドとフラグ