otel-instrumentation

OpenTelemetry 計装ガイド

高品質でコスト効率の高い OpenTelemetry テレメトリーを実装するための専門的なガイダンスです。

ルールとクイックリファレンス

ユースケース／ルール	説明
telemetry	エントリーポイント — シグナルの種類、相関、ナビゲーション
resolve-values	コードベースからの設定値の解決
verify-dependencies	追加前に計装パッケージとバージョンが存在することを確認
resources	リソース属性 — サービスの識別情報と環境
k8s	Kubernetes のデプロイ — Downward API、Pod 仕様
spans	スパン — 命名、種類、ステータス、衛生管理
logs	ログ — 構造化ロギング、重大度、トレースとの相関
metrics	メトリクス — インストゥルメントの種類、命名、単位、カーディナリティ
sensitive-data	機密データ — PII の防止、サニタイズ、編集
capture-database-query-parameters	言語ごとのプリペアドステートメントのパラメーター取得（Java、.NET、Python、Node.js、Go）
validation	テレメトリーの検証 — デプロイ後の確認チェックリスト
nodejs	Node.js の計装設定
go	Go の計装設定
python	Python の計装設定
java	Java の計装設定
scala	Scala の計装設定
dotnet	.NET の計装設定
ruby	Ruby の計装設定
php	PHP の計装設定
browser	ブラウザーの計装設定
nextjs	Next.js のフルスタック計装（App Router）

公式ドキュメント

• OpenTelemetry ドキュメント
• セマンティック規約
• Dash0 Integration Hub

はじめに

アプリケーションをゼロから計装するときは、次の手順に従ってください。

1. SDK ルールを選択する — 上の表から言語固有のルールを選びます（例：nodejs、python）。
2. リソース属性を設定する — resources に従って、サービスの識別情報と環境を定義します。
3. スパン、メトリクス、ログを追加する — spans、metrics、logs に従ってコードを計装します。
4. 機密データを保護する — sensitive-data に従って、エクスポート前に PII を除去します。
5. 検証する — validation のチェックリストを使って、テレメトリーがバックエンドに届いていることを確認します。

以下のスニペットは、Node.js で属性とステータスを含む完全なスパンを示しています。SDK の初期化、エクスポーターの設定、自動計装を含む完全なセットアップについては、nodejs を参照してください。

import { trace, SpanStatusCode } from '@opentelemetry/api';
const tracer = trace.getTracer('my-service', '1.0.0');

tracer.startActiveSpan('operation-name', async (span) => {
  try {
    span.setAttribute('user.id', userId);
    span.setAttribute('order.id', orderId);

    const result = await processOrder(orderId);

    span.setAttribute('order.status', result.status);
    span.setStatus({ code: SpanStatusCode.OK });
    return result;
  } catch (err) {
    // Record the exception as a structured log record, not span.recordException — see rules/spans.md
    span.setStatus({ code: SpanStatusCode.ERROR, message: `${err.name}: ${err.message}` });
    const spanContext = span.spanContext();
    logger.error('operation-name.failed', {
      'trace_id': spanContext.traceId,
      'span_id': spanContext.spanId,
      'exception.type': err.name,
      'exception.message': err.message,
      'exception.stacktrace': err.stack,
    });
    throw err;
  } finally {
    span.end();
  }
});

主な原則

量よりシグナル密度

すべてのテレメトリー項目は、次の3つの目的のいずれかに役立つものでなければなりません。

• 検出 - 問題が発生していることを特定するのに役立つ
• 特定 - 問題の発生箇所を絞り込むのに役立つ
• 説明 - 問題が発生した理由の理解に役立つ

いずれの目的にも役立たない場合は、出力しないでください。

SDK ではなくパイプラインでサンプリングします

各 SDK で AlwaysOn サンプラーを明示的に設定してください（OTEL_TRACES_SAMPLER=always_on）。 これにより、OpenTelemetry のデフォルトである ParentBased(root=AlwaysOn) が上書きされます。この設定では、信頼境界の外部にいる呼び出し元が traceparent ヘッダーを通じて、サービスのトレーシングを気づかれないまま無効にできてしまいます。 比率ベースの SDK サンプラーも設定しないでください。リクエストの結果が判明する前に、取り消せない判断が行われるためです。 サンプリングはすべて Collector に委ねてください。これにより、アプリケーションを再デプロイすることなく、ポリシーを一元的に変更できます。 詳しい理由と、ParentBased が許容される条件については、SDK sampling を参照してください。

SDK (AlwaysOn, set explicitly)  →  Collector (sampling)  →  Backend (retention)
             ↓                           ↓                       ↓
       All spans                   Head or tail            Storage policies
       exported                    sampling applied