OpenTelemetry の SDK は、共通の環境変数のセットを共有しているため、Java、Python、Node.js、.NET などで同じ設定が機能します。これはアプリケーションを設定する最も一般的な方法であり、プラットフォームが環境を設定するため、コンテナや Kubernetes に完璧に適合します。このガイドでは、最もよく使う変数を説明します。

各言語の SDK は、それぞれのペースで仕様を実装しているため、あまり一般的でない変数は、お使いの言語のドキュメントで確認してください。

必須のもの

export OTEL_SERVICE_NAME=checkout
export OTEL_RESOURCE_ATTRIBUTES=service.version=1.4.2,deployment.environment.name=staging
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf

• OTEL_SERVICE_NAME は service.name を設定します。バックエンドはすべてをこれでグループ化するため、最も重要な属性です。未設定の場合は、unknown_service という名前になります。OTEL_RESOURCE_ATTRIBUTES 内の service.name よりも優先されます。
• OTEL_RESOURCE_ATTRIBUTES は、サービスのバージョンや環境など、サービスを記述する key=value のペアのカンマ区切りのリストです。
• OTEL_EXPORTER_OTLP_ENDPOINT は、テレメトリの送り先です。Collector に向けます。
• OTEL_EXPORTER_OTLP_PROTOCOL は、grpc、http/protobuf、http/json のいずれかです。

エンドポイントとプロトコル：ポートが一致する必要がある

デフォルトは、HTTP では http://localhost:4318、gRPC では http://localhost:4317 です。HTTP のプロトコルでは、SDK は v1/traces、v1/metrics、v1/logs を、ベースのエンドポイントに追加します。OTEL_EXPORTER_OTLP_TRACES_ENDPOINT のようなシグナルごとのエンドポイントを設定した場合は、何も追加されず、与えられたとおりに使われます。

最もよくある間違いは、不一致です。gRPC をポート 4318 に、あるいは HTTP を 4317 に送ることです。プロトコルとポートを一緒に選んでください。仕様のデフォルトのプロトコルは http/protobuf ですが、SDK によっては gRPC がデフォルトのものがあるため、明示的に設定してください。

exporter の選択

export OTEL_TRACES_EXPORTER=otlp      # デフォルト
export OTEL_METRICS_EXPORTER=otlp     # デフォルト
export OTEL_LOGS_EXPORTER=otlp        # デフォルト

値には、otlp、console（ターミナルに出力。デバッグに便利）、シグナルをオフにする none があります。言語によっては、メトリクス用の prometheus や、トレース用の zipkin など、他のものもサポートしています。

OTLP exporter のオプション

export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer abc123,x-tenant=team-a"
export OTEL_EXPORTER_OTLP_TIMEOUT=10000       # ほとんどの SDK でミリ秒
export OTEL_EXPORTER_OTLP_COMPRESSION=gzip
export OTEL_EXPORTER_OTLP_CERTIFICATE=/etc/ssl/ca.pem
export OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE=/etc/ssl/client.pem
export OTEL_EXPORTER_OTLP_CLIENT_KEY=/etc/ssl/client.key

これらにはそれぞれ、OTEL_EXPORTER_OTLP_TRACES_TIMEOUT や OTEL_EXPORTER_OTLP_METRICS_ENDPOINT のような、シグナルごとのバリエーションがあり、ベースの変数より優先されます。HEADERS は、key=value のペアのカンマ区切りのリストで、すべての値は文字列です。TLS には https:// のエンドポイントを使い、プライベート認証局や相互 TLS には証明書の変数を使います。

伝播とサンプリング

export OTEL_PROPAGATORS=tracecontext,baggage    # デフォルト
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

• OTEL_PROPAGATORS は、どのヘッダーがサービス間でトレースのコンテキストを運ぶかを決めます。デフォルトは tracecontext,baggage（W3C）です。リクエストの経路上のすべてのサービスは、互換性のあるプロパゲーターを使う必要があり、そうでないと、境界でトレースが途切れます。古いシステムと相互運用する必要があるときにのみ、b3 などを追加します。
• OTEL_TRACES_SAMPLER のデフォルトは parentbased_always_on で、すべてを記録し、呼び出し元の決定に従います。head サンプリングには、OTEL_TRACES_SAMPLER_ARG=0.1 を持つ parentbased_traceidratio が、親の決定を尊重しながら、新しいトレースの約 10% を保持します。Collector で代わりにサンプリングする場合については、サンプリングのガイドで説明します。

バッチ処理と制限

バッチの設定は、メモリ使用量とエクスポートの頻度を制御します。仕様のデフォルト：

変数	デフォルト
OTEL_BSP_SCHEDULE_DELAY	5000 ms
OTEL_BSP_MAX_QUEUE_SIZE	2048
OTEL_BSP_MAX_EXPORT_BATCH_SIZE	512
OTEL_BSP_EXPORT_TIMEOUT	30000 ms
OTEL_BLRP_SCHEDULE_DELAY	1000 ms
OTEL_METRIC_EXPORT_INTERVAL	60000 ms
OTEL_ATTRIBUTE_COUNT_LIMIT	128
OTEL_SPAN_EVENT_COUNT_LIMIT	128

BSP はスパンのバッチプロセッサー、BLRP はログレコードのバッチプロセッサーです。負荷時にスパンが破棄されるのを見たら、キューのサイズを増やし、テスト中は、データポイントを 1 分待たずに済むよう、メトリクスの間隔を短くします（たとえば 10000）。

運用上のスイッチ

export OTEL_SDK_DISABLED=true     # 計装を削除せずにテレメトリをオフにする
export OTEL_LOG_LEVEL=debug       # SDK 自身の診断ログのレベル（デフォルトは info）

OTEL_SDK_DISABLED は、手早い緊急停止スイッチです。デバッグログは非常に冗長なので、本番では有効のままにしないでください。

Docker Compose と Kubernetes に設定する

Compose：

services:
  checkout:
    image: myorg/checkout:1.4.2
    environment:
      OTEL_SERVICE_NAME: checkout
      OTEL_RESOURCE_ATTRIBUTES: service.version=1.4.2,deployment.environment.name=staging
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_EXPORTER_OTLP_PROTOCOL: http/protobuf
      OTEL_TRACES_SAMPLER: parentbased_traceidratio
      OTEL_TRACES_SAMPLER_ARG: "0.25"

Kubernetes：

env:
  - name: OTEL_SERVICE_NAME
    value: checkout
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://otel-collector.observability.svc.cluster.local:4318
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: k8s.pod.name=$(POD_NAME),deployment.environment.name=staging
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name

Operator のガイドでは、アプリケーションのチームが手作業で設定しなくて済むように、Instrumentation リソースでこれらを自動的に注入する方法を示します。

優先順位と落とし穴

• コード内の設定は、通常、環境変数に優先し、シグナルごとの変数は、一般的なものに優先します。
• お使いの SDK が認識しない変数は、黙って無視されます。設定が何もしないように見えるときは、その言語の設定ページを確認してください。
• OTEL_RESOURCE_ATTRIBUTES にシークレットを入れないでください。すべてのテレメトリのラベルになります。
• エンドポイントにパスが含まれる場合（たとえばプロキシの背後）は、何も追加されないように、シグナルごとのエンドポイントの変数を使います。
• 変数のリストは、サービスごとに 1 か所（Compose ファイルや Helm の values ファイル）に保管し、変更がレビューされるようにします。

完全な一覧については、SDK の環境変数の仕様と OTLP exporter の設定を参照してください。