OpenTelemetryトレーシングをClaudeと実装する

Claude Codeにトレーシング設計を相談する

分散システムの可観測性向上において、OpenTelemetry（OTel）の導入は非常に効果的です。しかし、スパンの設計やメトリクスの粒度判断は意外と難しいもの。Claude Codeを活用すれば、この設計フェーズから一緒に進められます。

まずはClaude Codeにこんなプロンプトを投げてみましょう。

私のNode.jsアプリにOpenTelemetryを導入したいです。
エンドポイント /api/orders の処理で、DBアクセスと外部API呼び出しを
個別のスパンとして計測する実装を提案してください。

Claudeはスパンの親子関係や属性設計まで具体的に提案してくれます。設計意図を説明しながら出力してくれるため、チームへの共有資料としても使えます。

※エンドポイント: APIにアクセスするためのURL。例: `/api/users` や `/api/posts/123` など。※プロンプト: AIへの指示文。Claude Codeへの指示の質がそのまま出力の質に影響する。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

実装コードをClaudeに生成させる

設計が固まったら、実装コードの生成に進みましょう。Claude Codeは以下のような初期化コードをすぐに出力できます。

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'order-service',
  }),
  traceExporter: new OTLPTraceExporter({
    url: 'http://localhost:4318/v1/traces',
  }),
});

sdk.start();

さらに「DBクエリをスパンで囲む処理も書いて」と追加指示するだけで、スパンの開始・終了・エラーハンドリングまで含めたコードを連続して生成してくれます。コンテキストが維持されるため、会話を重ねるほど精度が上がります。

※コンテキスト: Claudeが一度に記憶・参照できる会話・コードの範囲。上限を超えると古い情報が失われる。

デバッグとメトリクス追加もClaude Codeで進める

トレースがCollectorに届かない、スパンが欠落するといったトラブルも、Claudeに相談できます。エラーログを貼り付けて「このエラーの原因と修正方法を教えて」と聞くだけで、設定ミスや依存バージョンの問題を特定してくれます。

メトリクス追加も同様です。以下のようにプロンプトを送ると、既存トレース実装に合わせたカウンターやヒストグラムのコードを生成してくれます。

先ほどのorderサービスに、注文処理時間を計測する
OpenTelemetryのヒストグラムメトリクスを追加してください。
エラー率もカウンターで記録したいです。

OTelの導入は手順が多く敬遠されがちですが、Claude Codeを相棒にすれば設計・実装・デバッグまでを一気通貫で進められます。まずは小さなサービス一つへの導入から始めてみてください。