分散トレーシングの連携

分散トレーシングでは、1 つのリクエストが複数のマイクロサービスを経由する際の呼び出し経路と所要時間を表示します。業務サービス側から OTLP で運用プラットフォームの Alloy にデータを送信し、Tempo に転送して保存します。

HAP/HDP のクラスター構成のみ対応

分散トレーシングは Kubernetes クラスター構成が対象です。単一サーバー（Docker Compose）構成には現在対応していません。

推奨方法：Istio sidecar による自動送信

業務サービスが Istio メッシュ内にある場合、sidecar が span を自動生成して送信するため、業務コードの変更は不要です。HAP/HDP のクラスター構成は通常、メッシュ内で稼働しています。

sidecar の注入だけではトレースは送信されません

Istio をインストールし、istio-injection=enabled を設定しても、デフォルトでは span は生成されません。Istio に送信先とサンプリング率を設定する必要があります。未設定でも通常はエラーが出ませんが、トレースページにデータは表示されません。

次のコマンドで設定を確認します。

kubectl -n istio-system get cm istio \\
  -o jsonpath='{.data.mesh}' | grep -A3 extensionProviders

出力がなければ未設定です。以下の手順で設定してください。

手順 1：Istio に運用プラットフォームの Alloy を送信先として登録する

kubectl -n istio-system edit configmap istio

次のような構造が表示されます。mesh の値自体が YAML テキストです。extensionProviders は、このテキストの最上位に、defaultConfig、rootNamespace と同じ階層で追加してください。

apiVersion: v1
kind: ConfigMap
metadata:
  name: istio
  namespace: istio-system
data:
  mesh: |-                                  # ← 文字列ブロックであることに注意
    defaultConfig:
      discoveryAddress: istiod.istio-system.svc:15012
    defaultProviders:
      metrics:
      - prometheus
    enablePrometheusMerge: true
    rootNamespace: istio-system
    trustDomain: cluster.local
    extensionProviders:                     # ← このブロック全体を追加
      - name: mdis-otel
        opentelemetry:
          service: ops-alloy.<運用プラットフォームの名前空間>.svc.cluster.local
          port: 4317
  meshNetworks: |-
    networks: {}

よくある設定ミス

① defaultConfig の中に入れないでください。 extensionProviders は mesh の最上位フィールドです。階層を間違えると istiod はエラーを出さずに無視します。設定が記載されていても span は生成されません。

② service には完全な FQDN を指定し、実際の名前空間に置き換えてください。 デフォルトのマニフェストは hap-ops を使用しますが、実際の環境では異なる場合があります。名前空間が誤っていると sidecar はサービスを名前解決できず、通常はエラーも表示されません。次のコマンドで確認できます。

kubectl get svc -A | grep ops-alloy

③ ポートは 4317（OTLP gRPC）です。4318 ではありません。 opentelemetry provider は gRPC を使用します。

変更後、istiod を再起動して設定を読み込み直します。

kubectl -n istio-system rollout restart deployment/istiod
kubectl -n istio-system rollout status deployment/istiod

設定を再取得し、追加したブロックが出力されることを確認します。

kubectl -n istio-system get cm istio -o jsonpath='{.data.mesh}' | grep -A4 extensionProviders

手順 2：サンプリングを有効にする

前の手順では送信先のみを設定しました。サンプリング率も設定してください。Telemetry を作成していない場合、サンプリング率は 0 で、span は生成されません。

kubectl apply -f - <<'EOF'
apiVersion: telemetry.istio.io/v1
kind: Telemetry
metadata:
  name: mdis-tracing
  namespace: istio-system      # Istio のルート名前空間に配置するとメッシュ全体に適用
spec:
  tracing:
    - providers:
        - name: mdis-otel      # 手順 1 の name と完全に一致させる
      randomSamplingPercentage: 100
EOF

Telemetry リソースが作成されたことを確認します。

kubectl get telemetry -A

検証時は 100 に設定し、確認後に下げてください

検証時は randomSamplingPercentage を 100 にすることを推奨します。10% では少数のリクエストがサンプリングされず、設定が反映されていないと誤認する場合があります。送信を確認したら 1～10 に戻してください。サンプリング率が高いほど Tempo のストレージ使用量と書き込み負荷が増えます。この値の変更時に istiod の再起動は不要ですが、反映には業務 Pod の再起動が必要です。

Telemetry API のバージョン

上記の例は telemetry.istio.io/v1 を使用しています（Istio 1.22 以降。1.29 で動作確認済み）。それ以前の Istio では v1alpha1 を使用します。その他のフィールドは同じです。次のコマンドで利用可能なバージョンを確認できます。

kubectl api-resources | grep telemetry

手順 3：業務 Pod を再起動する

sidecar が新しい設定を取得すると送信が開始されます。この手順を実行しないと、ここまでの設定は有効になりません。

kubectl -n <業務サービスの名前空間> rollout restart deployment/<名前>

あわせて、業務サービスの名前空間で注入が有効かを確認します。

kubectl get ns -L istio-injection

該当行が enabled であれば sidecar が注入されます。

手順 4：運用プラットフォームへの span の到着を確認する

次のコマンドで、運用プラットフォームの Alloy が span を受信しているかを確認します。

kubectl -n <運用プラットフォームの名前空間> exec deploy/ops-alloy -- \
  curl -s localhost:12345/metrics | grep otelcol_receiver_accepted_spans_total

サービス間の呼び出しを数回実行してから、再度確認してください。メトリクスの値が増えていれば、送信経路は正常です。

otelcol_receiver_accepted_spans_total{...,transport="grpc"} 83

値が 0 のまま、またはメトリクスが見つからない場合は、次を確認してください。

状況	主な原因
値が 0	業務 Pod が未再起動（手順 3）、またはサンプリング率が低くリクエストがサンプリングされていない
メトリクスが存在しない	Alloy の OTLP 受信が無効。`ops-alloy` Service が 4317 を公開しているか確認
値は増えるが画面に表示されない	Alloy → Tempo の経路に異常。`ENV_TEMPO_GRPC_URL` と ops-tempo コンテナーのログを確認

送信先のエンドポイント

Alloy の OTLP 受信ポートは次のとおりです。

プロトコル	ポート
OTLP gRPC	`4317`
OTLP HTTP	`4318`

アプリケーションが OpenTelemetry SDK を使用している場合は、exporter を上記のエンドポイントに向けてください。クラスター内では、http://ops-alloy.<運用プラットフォームの名前空間>.svc.cluster.local:4317 のように Service DNS を使用します。名前空間は実際の値に置き換えてください。kubectl get svc -A | grep ops-alloy で確認できます。

別クラスターからは直接アクセスできません

ops-alloy は ClusterIP で、運用プラットフォームがあるクラスター内でのみ名前解決できます。別クラスターから送信する場合は、NodePort または Ingress で 4317 を公開する必要があります。トレースデータは大容量になるため、公開方法とレート制限は実際のネットワーク環境に合わせて設計してください。

Alloy から Tempo への転送先は ENV_TEMPO_GRPC_URL で設定します。デフォルトは http://ops-tempo:4317 で、標準構成では変更不要です。

データの保持と保存先

トレースデータの保持期間は ENV_TEMPO_RETENTION で設定し、デフォルトは 30 日間です。詳細は環境変数を参照してください。

ノードのディスク容量に依存せず長期間保存する場合は、デプロイ時に Tempo 用のオブジェクトストレージバケットを用意してください。推奨名は mdis-tempo です。オブジェクトストレージを参照してください。

動作確認

連携後、サービス間の呼び出しを数回行い、分散トレーシングページを開きます。上部の 3 つの概要グラフ（リクエスト数／エラーレート／P95 レイテンシー）にデータが表示され、下部の Recent Traces 一覧にトレースの詳細が表示されれば、連携は完了です。

推奨方法：Istio sidecar による自動送信​

手順 1：Istio に運用プラットフォームの Alloy を送信先として登録する​

手順 2：サンプリングを有効にする​

手順 3：業務 Pod を再起動する​

手順 4：運用プラットフォームへの span の到着を確認する​

送信先のエンドポイント​

データの保持と保存先​

動作確認​