OpenTelemetry

トレース・メトリクス・ログを自分のコレクター/バックエンドへ送るオプトインの OTLP エクスポート。

shunt は トレース・メトリクス・ログ を OTLP/HTTP で自分の OpenTelemetry Collector(または OTLP 互換バックエンド)へエクスポートできます。オプトインで、デフォルトはオフ です — [otel] セクションがなければ、何もマシンの外に出ません — そして Sentry とは独立して動作するため、どちらか一方でも両方でも有効にできます。

有効化

キー 1 つで有効になります。コレクターの OTLP/HTTP レシーバーを指定してください:

[otel]
endpoint = "http://localhost:4318"   # OTLP/HTTP のベース URL。shunt が /v1/{traces,metrics,logs} を付加

それ以外はすべて妥当なデフォルトを持ちます:

[otel]
endpoint = "http://localhost:4318"
service_name = "shunt"     # (デフォルト) service.name リソース属性
environment = "prod"       # 任意: deployment.environment.name
sample_ratio = 1.0         # (デフォルト) ヘッドベースのトレースサンプリング、0.0–1.0
traces = true              # (デフォルト) リクエストスパンをエクスポート
metrics = true             # (デフォルト) 使用量メトリクスをエクスポート
logs = true                # (デフォルト) ログイベントをエクスポート(stderr ログには影響なし)
include_session_id = false # (デフォルト) クライアントのセッション id をスパンから除外

[otel.headers]             # 任意: リクエストごとのヘッダー(例: ホスト型コレクターのトークン)
authorization = "Bearer <token>"

endpoint = ""(例: SHUNT_OTEL__ENDPOINT="")にすると、セクションを削除せずにエクスポートを再び無効化できます。無効なエンドポイント、http(s) 以外の URL、範囲外の sample_ratio は 起動エラー になるため、タイプミスですべてのエクスポートが黙って失われることはありません。

3 つのシグナル

シグナル	エクスポートされるもの	備考
トレース	リクエストごとの `proxy_request` スパン	`sample_ratio` によるヘッドベースサンプリング。低カーディナリティで、リクエスト/レスポンス本文は含まない。
メトリクス	以下に示す低カーディナリティの系列	`[sentry] metrics = true` のときに shunt が Sentry へ送るものと同じ系列。
ログ	shunt の `tracing` ログイベントを OTLP にブリッジ	stderr ログには影響しない。

各シグナルは traces / metrics / logs で個別にオン/オフできます。

メトリクス系列

系列	種類	属性	意味
`shunt.requests`	カウンター	`provider`, `model`, `http.response.status_code`	プロキシされた推論リクエスト。
`shunt.latency`	ヒストグラム(ms)	`provider`, `model`, `http.response.status_code`	ストリームではヘッダーまで、それ以外では応答全体のレイテンシ。
`shunt.ttft`	ヒストグラム(ms)	`provider`, `model`	リクエスト開始から最初の SSE body chunk までの時間。
`shunt.stream_outcome`	カウンター	`provider`, `model`, `outcome`	SSE の最終結果を 1 件記録: `completed`, `error_event`, `upstream_cut`, `client_disconnect`。
`shunt.tokens`	カウンター	`provider`, `model`, `kind`	最後に報告されたストリーミング token usage (`input`, `output`, `cache_read`, `cache_creation`)。非ストリーミングは記録しない。
`shunt.codex_continuation`	カウンター	`provider`, `outcome`	Codex WebSocket continuation の hit または fallback。
`shunt.codex_client_events`	カウンター	`event`	サニタイズ済みイベント名ごとの Codex CLI analytics イベント。payload とプロパティは破棄される。
`shunt.upstream_retries`	カウンター	`provider`, `reason`	回数制限付きの一時的な upstream retry。
`shunt.failover`	カウンター	`provider`, `state`	順序付きアップストリームのフェイルオーバー遷移: `attempted`, `advanced`, `exhausted`。
`shunt.pool.quota_utilization`	ゲージ	`provider`, `window`	`5h`, `7d`, `7d_oi` ごとに、有効で観測済みかつ期限切れでない quota 値の最小 utilization。
`shunt.pool.rotations`	カウンター	`provider`, `reason`	アカウントからの切り替えと pool exhaustion の回数。

プライバシー

shunt は メトリクスとトレース においてリクエスト/レスポンス本文・ヘッダー・認証情報を一切エクスポートしません。

メトリクスとトレース は低カーディナリティで本文を含みません。OTLP トレースエクスポートでは、リクエストスパンのクライアント セッション id は、include_session_id = true(デフォルトはオフ)のときのみ、しかもトレースエクスポートが有効な間だけコレクターへ送られます。同じルールは Sentry のトレースエクスポート([sentry] traces_sample_rate / include_session_id)にも適用されます。スパンのエクスポートが一切有効でない場合、id は従来どおりローカルのリクエストスパンにだけ残ります。
ログは shunt 自身の診断イベントをそのまま反映するため、stderr ログと同様に、リクエスト由来のフィールド(アップストリームのエラー本文、認証済みクライアント id)を含みうる点に注意してください。厳密に本文なしでエクスポートしたい場合は logs = false にして、メトリクス/トレースだけを残します。

エクスポートされるリソースは service.*、telemetry.sdk.*、および environment が設定されている場合は deployment.environment.name を広告します — host や process detector は動かないため、マシンのホスト名は付与されません — これに標準の OTEL_RESOURCE_ATTRIBUTES で設定した値が加わります。

標準の `OTEL_` 環境変数

endpoint と service_name はこの設定から取得され、OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_SERVICE_NAME より 優先されます。
標準の OTEL_EXPORTER_OTLP_HEADERS と OTEL_RESOURCE_ATTRIBUTES は、[otel.headers] と組み込みのリソース属性の上に マージされます。

すべてのキーは [otel] 設定リファレンスを参照してください。