OpenTelemetry Demo 入門:決済エラーをトレースで追う

OpenTelemetry Demo 3.1.0 を Docker Compose で起動し、決済の成功時と失敗時を Jaeger で比較。Collector から Guance にもトレースを送る手順を紹介します。

ベストプラクティス
アプリケーションのテレメトリーを調べるイメージ

OpenTelemetry Demo で最初に試すなら、決済を一度失敗させてみると分かりやすい。ブラウザで確認できるのは注文が通らなかったことまでだ。トレースを開けば、注文処理が決済サービスに届いたか、請求処理のどこでエラーになったかを追える。公式のサンプルアプリ Astronomy Shop なら、自分のアプリケーションに計装を加える前にこの流れを試せる。

この記事は Demo 3.1.0 を対象とする。Compose の設定、プロキシのルート、決済ハンドラーの挙動をバージョン固定のソースで確認した。コンテナ一式の起動と外部 DataKit への取り込みは検証範囲に含めていない。

オブザーバビリティ用の構成を重ねて起動する

Astronomy Shop は、ストア画面、商品カタログ、カート、注文、決済などからなる多言語のサンプルアプリだ。フル構成では Kafka が入り、不正検知や会計サービスがメッセージを処理する。Collector がテレメトリーを受け取り、Jaeger、Prometheus、OpenSearch、Grafana などで調べられる。サービスごとに出力するシグナルが異なるので、見たいデータがあるときはテレメトリーの一覧を先に確認しておくとよい。アーキテクチャ(英語) · テレメトリーの一覧(英語)

Docker と Compose v2 が動く検証専用のマシンを用意する。公式ガイドの目安はフル構成でアプリ用メモリ 6 GB、ディスク 14 GB。Compose はホストのパスや Docker ソケットをマウントし、ポートも公開する。隔離した環境で、用意されているサンプルデータを使う。Docker での起動要件(英語) · 3.1.0 のリリース(英語)

git clone --branch 3.1.0 --depth 1 https://github.com/open-telemetry/opentelemetry-demo.git
cd opentelemetry-demo
export DEMO_VERSION=3.1.0
docker compose --env-file .env --env-file .env.override \
  -f compose.yaml -f compose.full.yaml \
  -f compose.observability.yaml -f compose.extras.yaml up -d

docker compose up だけで読み込むのは基本構成だ。上のコマンドでは、フル構成、可観測性のバックエンド、追加設定を順に重ねている。ストアと調査に使うサービスの起動を待ち、既定のポートから開く。

ローカル URL 確認する内容
http://localhost:8080/ ストアを開き、テスト注文を送る。
http://localhost:8080/jaeger/ui/ 注文のトレースを探す。
http://localhost:8080/grafana/ 構成済みのダッシュボードとデータソースを見る。
http://localhost:8080/loadgen/ 負荷生成ツールのテストトラフィックを確認する。
http://localhost:8080/feature/ flagd UI でシナリオを切り替える。
http://localhost:8080/telemetry/ サービスごとに記録されるテレメトリーを調べる。

正常な注文と決済が失敗した注文を比べる

まず paymentFailure を off にして、サンプルの決済情報で注文を一件送る。時刻を控え、Jaeger で checkout を選んでその時間帯のトレースを探す。決済サービス payment に進み、charge スパンを開く。負荷生成ツールのリクエストが多ければ、検索範囲を絞るか、比較している間だけ負荷を止める。

次は flagd UI で paymentFailure のデフォルトバリアントを 100% に変えて保存する。もう一度サンプル注文を送ると、対象バージョンの決済ハンドラーはテスト用の例外を発生させ、charge スパンにエラーを記録する。二つのトレースを開いて、どのスパンに最初のエラーが現れたかを確かめる。確認が済んだら off に戻す。フィーチャーフラグ(英語) · 3.1.0 の決済ハンドラー

スパンを見れば一件の注文で何が起きたか分かる。時間帯全体の傾向はメトリクスで確認する。ログから詳しい経緯を追えるのは、該当サービスがログを出し、トレース ID を参照できる場合だ。ログが見つからないときは、サービス側の出力と Collector のログパイプラインを調べる。

Collector の中でデータの行き先を追う

アプリケーションは OTLP で Collector に送信する。基本設定がレシーバーと処理を定義し、可観測性の設定を重ねるとトレースは Jaeger、メトリクスは Prometheus、ログは OpenSearch に送られる。span_metrics コネクターはスパンからメトリクスも作る。最後の追加設定を使えば、アプリを変えずに行き先を増やせる。Collector の基本設定 · 可観測性の追加設定

フル構成なら、注文から Kafka のコンシューマーに至る処理も追える。非同期の処理を読むときは、スパンの親子関係とリンクのどちらでつながっているかを確認する。サンプリングを試すときは、トレースの方針を変えて、どのトレースが残るかを見る。検証環境全体のトラフィックを減らしたい場合は負荷生成側を調整する。トレースを間引くだけで、メトリクスとログの流量が一律に減るわけではない。

トレースを Guance にも送る

Collector のコンテナからプライベートネットワーク経由で DataKit に接続できるなら、まずトレースを複製する。src/otel-collector/otelcol-config-extras.yml で OTLP/HTTP Protobuf エクスポーターを定義し、既存のトレースパイプラインに加える。例の URL はコンテナから到達できる接続先に置き換える。DataKit の既定の HTTP ポートは 9529、トレースのパスは /otel/v1/traces だ。TLS と認証は利用環境に合わせて設定する。DataKit の OpenTelemetry 連携

exporters:
  otlp_http/datakit:
    traces_endpoint: https://datakit.example.com/otel/v1/traces
service:
  pipelines:
    traces:
      exporters: [debug, otlp_grpc/jaeger, span_metrics, otlp_http/datakit]

Collector が設定を重ねる際、配列は上書きされる。この構成で既存の出力を残すには、Jaeger、デバッグ出力、span_metrics コネクターを同じ一覧に入れておく。変更後は同じ Compose の構成で Collector を再起動する。データが届いたら、先ほどの正常時と異常時の注文で、Guance のサービス名とスパン階層を照合する。メトリクスとログを転送する場合は、それぞれのエンドポイントとパイプラインを別途設定する。

検証環境でよく出る疑問

フル構成が重い場合は? 公式の最小構成では可観測性のバックエンドを残し、Kafka とそれに依存するサービスを省く。公式ガイドのアプリ用メモリの目安は約 3 GB。依存関係を保つため、サポートされている構成を使う。

計装コードは本番に持っていける? 使っている言語の SDK の例を出発点に、リソースの識別情報、サンプリング、機密データの扱いを本番向けに決める。検証ではサンプルデータを使い、生の機密情報を出力するフラグは無効にしておく。

Kubernetes でも試せる? 公式 Helm チャートがある。テスト用クラスターで公式の values、リソース要件、ポートフォワーディングの手順に従う。Kubernetes での起動(英語)

関連記事

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ