opentelemetry

OpenTelemetry - クイックリファレンス

完全版リファレンス：コンテキスト伝播、詳細なメトリクス API、Collector の設定、Docker Compose スタック、サンプリング戦略、セマンティック規約については、advanced.md を参照してください。

詳細情報：包括的なドキュメントについては、テクノロジーに opentelemetry を指定して mcp__documentation__fetch_docs を使用してください。

概念

┌─────────────────────────────────────────────────────────────┐
│                      OpenTelemetry                          │
├─────────────────┬─────────────────┬─────────────────────────┤
│     Traces      │     Metrics     │         Logs            │
│  (Distributed)  │  (Aggregated)   │     (Structured)        │
├─────────────────┴─────────────────┴─────────────────────────┤
│                    OTLP Protocol                            │
├─────────────────────────────────────────────────────────────┤
│                 Collector (optional)                        │
├─────────────────────────────────────────────────────────────┤
│  Jaeger │ Zipkin │ Prometheus │ Grafana │ DataDog │ etc.    │
└─────────────────────────────────────────────────────────────┘

Node.js のセットアップ

npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http

基本設定

// tracing.ts - Load FIRST before any other imports
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: 'my-service',
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

process.on('SIGTERM', () => {
  sdk.shutdown().finally(() => process.exit(0));
});

アプリケーションのエントリーポイント

// index.ts
import './tracing'; // MUST be first import
import express from 'express';

const app = express();

手動トレース

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('my-service', '1.0.0');

async function processOrder(orderId: string) {
  return tracer.startActiveSpan('process-order', async (span) => {
    try {
      span.setAttribute('order.id', orderId);
      await processOrderLogic(orderId);
      span.setStatus({ code: SpanStatusCode.OK });
    } catch (error) {
      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
      span.recordException(error);
      throw error;
    } finally {
      span.end();
    }
  });
}

Spring Boot のセットアップ

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-otel</artifactId>
</dependency>
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-otlp</artifactId>
</dependency>

management:
  tracing:
    sampling:
      probability: 1.0
  otlp:
    tracing:
      endpoint: http://localhost:4318/v1/traces

環境変数

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1  # 10% sampling

このスキルを使用しない場合

• シンプルなアプリケーションのログ記録：代わりにロギングフレームワークを使用します
• モノリシックアプリケーション：過剰な場合があります
• ベンダー固有の APM：DataDog、New Relic には独自の SDK があります
• 開発／デバッグのみの場合：標準のログ記録で十分な場合があります
• レガシーシステム：移行に多大な労力がかかる場合があります

アンチパターン

アンチパターン	問題点	解決策
すべての関数でスパンを作成する	大きなオーバーヘッドが発生します	意味のある操作のみをスパンにします
本番環境で 100% サンプリングする	パフォーマンスに影響し、コストがかかります	1～10% のサンプリングを使用します
コンテキストを伝播しない	分散トレースが途切れます	サービス境界で注入／抽出します
スパン属性に PII を記録する	セキュリティ／コンプライアンス違反になります	機密データをフィルタリングします
スパンの終了を忘れる	メモリリークが発生します	必ず finally ブロックでスパンを終了します
同期エクスポーターを使用する	アプリケーションをブロックします	バッチプロセッサーを使用します

クイックトラブルシューティング

問題	原因	解決策
トレースが表示されない	エクスポーターが設定されていません	OTEL_EXPORTER_OTLP_ENDPOINT を確認します
メモリ使用量が多い	スパンが多すぎます	サンプリングを有効にします
コンテキスト伝播が欠落している	ヘッダーを注入していません	伝播 API を使用します
パフォーマンスが低下している	サンプリング率が高い	1～10% に下げます
SDK の初期化エラー	インポート順序が誤っています	他のインポートより前に SDK を初期化します

メトリクスの監視

メトリクス	目標
トレースレイテンシ（p99）	オーバーヘッド < 10ms
スパンのドロップ率	< 1%
Collector のメモリ使用量	< 1GB
エクスポート成功率	> 99%

チェックリスト

• 他のインポートより前に SDK を初期化する
• リソース属性を設定する
• コンテキスト伝播を実装する
• サンプリング戦略を定義する
• グレースフルシャットダウンを設定する
• Collector をデプロイする
• ダッシュボードを作成する（Grafana）
• アラートを設定する

リファレンス

詳細情報：包括的なドキュメントについては、テクノロジーに opentelemetry を指定して mcp__documentation__fetch_docs を使用してください

• OpenTelemetry ドキュメント