opentelemetry

OpenTelemetry 実装ガイド

概要

OpenTelemetry（OTel）は、テレメトリデータ（トレース、メトリクス、ログ）の計装、生成、収集、エクスポートを行うためのベンダー中立な可観測性フレームワークです。このスキルでは、Kubernetes 環境で OTEL を実装するためのガイダンスを提供します。

クイックスタート

Kubernetes に OTEL Collector をデプロイする

# Add Helm repo
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update

# Install with basic config
helm install otel-collector open-telemetry/opentelemetry-collector \
  --namespace monitoring --create-namespace \
  --set mode=daemonset

OTLP 経由でテストデータを送信する

# gRPC endpoint: 4317, HTTP endpoint: 4318
curl -X POST http://otel-collector:4318/v1/traces \
  -H "Content-Type: application/json" \
  -d '{"resourceSpans":[]}'

基本概念

シグナル：テレメトリデータには次の 3 種類があります。

• トレース：サービス間の分散リクエストフロー
• メトリクス：数値測定値（カウンター、ゲージ、ヒストグラム）
• ログ：構造化データまたは非構造化データを含むイベント記録

Collector のコンポーネント：

• レシーバー：データを受け入れます（OTLP、Prometheus、Jaeger、Zipkin）
• プロセッサー：データを変換します（batch、memory_limiter、k8sattributes）
• エクスポーター：データを送信します（prometheusremotewrite、loki、otlp）
• エクステンション：機能を追加します（health_check、pprof、zpages）

Collector の設定

基本的なパイプライン構造

config:
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: ${env:MY_POD_IP}:4317
        http:
          endpoint: ${env:MY_POD_IP}:4318

  processors:
    batch:
      timeout: 10s
      send_batch_size: 1024
    memory_limiter:
      check_interval: 5s
      limit_percentage: 80
      spike_limit_percentage: 25

  exporters:
    prometheusremotewrite:
      endpoint: "http://prometheus:9090/api/v1/write"
    loki:
      endpoint: "http://loki:3100/loki/api/v1/push"

  service:
    pipelines:
      metrics:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [prometheusremotewrite]
      logs:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [loki]
      traces:
        receivers: [otlp]
        processors: [memory_limiter, batch]
        exporters: [otlp/tempo]

Kubernetes 属性の付加

processors:
  k8sattributes:
    auth_type: "serviceAccount"
    passthrough: false
    filter:
      node_from_env_var: ${env:K8S_NODE_NAME}
    extract:
      metadata:
        - k8s.pod.name
        - k8s.namespace.name
        - k8s.deployment.name
        - k8s.node.name

デプロイモード

モード	ユースケース	メリット	デメリット
DaemonSet	ノードレベルの収集	網羅的なカバレッジ、ホストメトリクス	リソース使用量が多い
Deployment	集中型ゲートウェイ	スケーラブルで、管理が容易	単一障害点
Sidecar	Pod ごとの収集	分離され、きめ細かく制御可能	Pod ごとにリソースオーバーヘッドが発生

一般的なパターン

開発環境

• 可視性を高めるため、デバッグエクスポーターを有効にします
• リソース制限を低く設定します（CPU 250m、メモリ 512Mi）
• コスト削減のため、スポットインスタンスの許容設定を含めます

本番環境

• サンプリングを実装します（トレースの 10～50％）
• バッチサイズを大きくします（2048～4096）
• オートスケーリングと PodDisruptionBudget を有効にします
• すべてのエンドポイントで TLS を使用します

詳細なリファレンス

詳しいガイダンスについては、以下を参照してください。

• Collector の設定：COLLECTOR.md
• Kubernetes のデプロイ：KUBERNETES.md
• トラブルシューティング：TROUBLESHOOTING.md
• 計装：INSTRUMENTATION.md

検証コマンド

# Check collector pods
kubectl get pods -n monitoring -l app.kubernetes.io/name=otel-collector

# View collector logs
kubectl logs -n monitoring -l app.kubernetes.io/name=otel-collector --tail=100

# Test OTLP endpoint
kubectl run test-otlp --image=curlimages/curl:latest --rm -it -- \
  curl -v http://otel-collector.monitoring:4318/v1/traces

# Validate config syntax
otelcol validate --config=config.yaml

主要な Helm チャートの値

mode: "daemonset"  # or "deployment"
presets:
  logsCollection:
    enabled: true
  hostMetrics:
    enabled: true
  kubernetesAttributes:
    enabled: true
  kubeletMetrics:
    enabled: true
useGOMEMLIMIT: true
resources:
  limits:
    cpu: 500m
    memory: 1Gi
  requests:
    cpu: 100m
    memory: 256Mi

---

注意点

• パイプラインの末尾にある Collector の tail_sampling は、処理中のバッファーを解放しません — 後段で行われた破棄の判断でもメモリを保持するため、負荷時に OOM が発生します。
• 自動計装と手動計装を併用すると、トレースが二重にカウントされることがあります — サービスごとにどちらか一方の方式を選ぶか、サンプラーで明示的に重複を排除してください。
• コンテキスト伝播：HTTP の B3 ヘッダーと W3C の traceparent ヘッダーは自動変換されません。混在環境では、気付かないうちにトレースの連続性が失われます。
• OTel SDK と Collector のプロトコルバージョン：マイナーバージョンの不一致により、属性が気付かないうちに欠落することがあります（特にセマンティック規約の属性）。
• リソース検出ではプラットフォーム属性（cloud.account.id、host.id）が追加され、トレースが肥大化します。ルーティングに使用しない場合は無効にしてください。
• バッチプロセッサーとメモリーリミッターの順序：パイプラインではリミッターをバッチの前に置く必要があります。そうしないと、メモリーの逼迫時にバックプレッシャーがかからず、バッチが破棄されます。