tempo

Grafana Tempo

ドキュメント: https://grafana.com/docs/tempo/latest/

コスト効率に優れた分散トレーシングです。OTLP／Jaeger／Zipkin／OpenCensus／Kafka を受け付けます。Parquet ブロックを S3／GCS／Azure に保存します。

前提条件

• Docker（クイックスタート）または Kubernetes（本番環境）
• 分散デプロイ用のオブジェクトストレージバケット（S3／GCS／Azure）
• OTLP を出力するアプリ、または合成トラフィックを生成する tempo-cli
• クエリ用の Tempo データソースを備えた Grafana スタック

一般的なワークフロー

1. Tempo をローカルで起動し、データの取り込みを確認する

# 1. Start the official Docker Compose example
git clone https://github.com/grafana/tempo.git
cd tempo/example/docker-compose/local
mkdir -p tempo-data
docker compose up -d

# 2. Verify readiness
curl -sf http://localhost:3200/ready                              # → "ready"

# 3. Send a synthetic OTLP span (full payload in scratch terminal)
curl -X POST -H 'Content-Type: application/json' \
  http://localhost:4318/v1/traces \
  -d '{"resourceSpans":[{"resource":{"attributes":[{"key":"service.name","value":{"stringValue":"my-service"}}]},
       "scopeSpans":[{"spans":[{"traceId":"5B8EFFF798038103D269B633813FC700","spanId":"EEE19B7EC3C1B100",
       "name":"my-op","startTimeUnixNano":1689969302000000000,"endTimeUnixNano":1689969302500000000,"kind":2}]}]}]}'

# 4. Verify the trace landed (ingestion-counter > 0 and the trace is fetchable)
curl -s http://localhost:3200/metrics | grep tempo_distributor_spans_received_total | head
curl -s http://localhost:3200/api/v2/traces/5B8EFFF798038103D269B633813FC700 | jq '.batches | length'
# Expect > 0.

# 5. In Grafana → Explore → Tempo, run TraceQL: {resource.service.name="my-service"}

2. Alloy 経由でアプリからトレースを送信する

// alloy.river
otelcol.receiver.otlp "default" {
  grpc { endpoint = "0.0.0.0:4317" }
  http { endpoint = "0.0.0.0:4318" }
  output { traces = [otelcol.exporter.otlp.tempo.input] }
}

otelcol.exporter.otlp "tempo" {
  client {
    endpoint = "tempo:4317"
    tls { insecure = true }
  }
}

# Verify Alloy forwarded successfully
curl -s http://localhost:12345/metrics | grep otelcol_exporter_sent_spans
# Then: same Grafana → Explore → Tempo check.

3. TraceQL を記述して実行する

# Slow requests from a service
{ resource.service.name = "frontend" && duration > 1s }

# Server span that has a downstream error (structural)
{ kind = server } >> { status = error }

# Error rate per service (metrics)
{ status = error } | rate() by (resource.service.name)

演算子とスコープのチートシート、組み込み項目の一覧、メトリクス関数の全容については、references/traceql.md を参照してください。

# Via the API
curl -sG --data-urlencode 'q={resource.service.name="frontend" && duration > 1s}' \
  --data-urlencode "start=$(date -d '1h ago' +%s)" --data-urlencode "end=$(date +%s)" \
  http://localhost:3200/api/search | jq '.traces | length'

4. Kubernetes にデプロイする（Helm）

helm repo add grafana https://grafana.github.io/helm-charts
helm install tempo grafana/tempo-distributed --version 1.61.3 \
  --set storage.trace.backend=s3 \
  --set storage.trace.s3.bucket=my-tempo-bucket \
  --set storage.trace.s3.region=us-east-1

# Verify every pod is Ready (distributor, ingester, querier, query-frontend, compactor)
kubectl get pods -n default -l app.kubernetes.io/instance=tempo
kubectl port-forward svc/tempo-query-frontend 3200:3200 &
curl -sf http://localhost:3200/ready

マルチテナンシー

multitenancy_enabled: true
# All requests must include header: X-Scope-OrgID: <tenant-id>

アーキテクチャ、ポート、パフォーマンスチューニング、メトリクスジェネレーターの設定、マルチテナントのクライアントスニペット、トレースからログ／メトリクス／プロファイルへのデータソースの全容については、references/architecture-and-operations.md を参照してください。

トラブルシューティング

• /ready → 503 → インジェスターがまだ参加中です。tempo_ingester_* メトリクスとログを確認してください。
• プッシュ時に 429 → max_outstanding_per_tenant またはテナントごとの取り込み上限を引き上げてください。
• 「Explore にトレースが表示されない」→ 書き込み側と Grafana データソースで X-Scope-OrgID が一致していることを確認してください。
• TraceQL が遅い → start／end の範囲を狭め、service.name フィルターを追加し、頻繁に使う属性用の専用 Parquet 列を有効にしてください。

リソース

• Tempo のドキュメント
• TraceQL リファレンス
• references/traceql.md — TraceQL チートシートの全容
• references/architecture-and-operations.md — コンポーネント、ポート、Helm、チューニング、データソースへのリンク