トレース

分散トレーシングは Prom と Loki に続く 3 つ目の L1 バックエンドです。それらと同じく ADR-014 に従います：edge は直接プッシュ、manager はクエリのみ。

データプレーン

text

your apps (OTLP gRPC/HTTP)
    │
    ▼
edge:
  otelcol (subprocess plugin)
    └─ remote OTLP → tempo:4317
                          │
                          ├─ trace storage (S3-compatible blob)
                          │
                          └─ metrics_generator → traces_spanmetrics_*
                                                       │
                                                       ▼
                                                 prometheus:9090

otelcol は edge エージェント下のプラグインとして動きます（promtail と同じ監督モデル —— ログを参照）。コレクターはホスト上で gRPC（:4317）と HTTP（:4318）の両方を受け、バッチ化し、HTTPS でクラウドの Tempo に転送します。

アプリは Ongrid を知る必要はない

アプリケーションの OTel エクスポーターを http://localhost:4318（または gRPC 相当）に向けて設定するだけ。ローカル otelcol が認証 + バッチング + クラウドへの旅を処理します。Ongrid を取り外すには env var を 1 つ削除する —— コードは無傷です。

Spanmetrics ジェネレーター

compose の Tempo デプロイメントは metrics_generator を有効化しています。スパンのバッチごとに、同じ Prom に emit し戻される派生メトリクスが 3 つ生成されます：

系列	ソース
`traces_spanmetrics_calls_total`	(service, operation, status_code) ごとに 1 つのカウンター
`traces_spanmetrics_latency_bucket`	スパン時間のヒストグラム
`traces_spanmetrics_size_bucket`	オプション、デフォルトオフ

これがトレースアラートをメトリクスアラートのように感じさせる耐荷重の仕掛けです：アラート evaluator は Prom にクエリし、データは Tempo に住みます。

アラート種別

`trace_latency`

json

{
  "kind": "trace_latency",
  "scope_type": "global",
  "conditions_json": {
    "service": "payments-api",
    "operation": "POST /v1/charge",
    "quantile": "p95",
    "window": "5m",
    "threshold_ms": 800
  }
}

以下にコンパイルされます：

promql

histogram_quantile(
  0.95,
  sum by (le) (rate(traces_spanmetrics_latency_bucket{
    service_name="payments-api", span_name="POST /v1/charge"
  }[5m]))
) * 1000 > 800

operation はオプション —— サービス全体のレイテンシなら落とします。 compileTraceLatencyRule 参照。

サポート quantile：p50 / p95（デフォルト） / p99。文字列形式は UI フォームピッカーを簡潔に保つために存在します。コンパイラが histogram_quantile が求める float にマップします。

`trace_error_rate`

json

{
  "kind": "trace_error_rate",
  "scope_type": "global",
  "conditions_json": {
    "service": "payments-api",
    "window": "5m",
    "operator": ">",
    "threshold_pct": 1.0
  }
}

以下にコンパイルされます：

promql

100 * (
  sum by (service_name) (rate(traces_spanmetrics_calls_total{
    service_name="payments-api", status_code="STATUS_CODE_ERROR"
  }[5m]))
  / sum by (service_name) (rate(traces_spanmetrics_calls_total{
    service_name="payments-api"
  }[5m]))
) > 1.0

STATUS_CODE_ERROR リテラルは spanmetrics ジェネレーターが emit するものです。代替のスパンステータス規約には独自の種別が必要です。

ツール

`query_traceql`

Tempo の TraceQL エンドポイントへの直接パススルー (query_traceql_basetool.go)。 operator が特定のトレース ID を訊いたとき investigator ペルソナが使用 —— 例：「過去 30 分の payments-api の遅いトレースを探して」。

text

{ resource.service.name="payments-api" } | duration > 800ms

基底クライアントは internal/pkg/tracequery。バックエンドから切り離したパッケージ名はわざと —— Jaeger / Zipkin クライアントが表面をリネームせず後から投入できます。

`correlate_incident`

investigator ペルソナが始めに使う合成ツール。インシデントの発火ウィンドウ周りの Prom + Loki + Tempo シグナルを単一のファンアウト呼び出しで取得。 4-5 個の逐次的なツール呼び出しを 1 つに削減します —— 調査ごとの予算が 10 ツール呼び出しのときに重要です。

correlate_incident_basetool.go 参照。

トレース ​

データプレーン ​

Spanmetrics ジェネレーター ​

アラート種別 ​

trace_latency ​

trace_error_rate ​

ツール ​

query_traceql ​

correlate_incident ​

関連 ​