環境変数は、少数の設定にはうまく機能しますが、複数の exporter、カスタムの processor、サンプリングのルールが必要になると、扱いにくくなります。宣言的な設定は、それらを、SDK 全体（resource、プロパゲーター、tracer、meter、logger のプロバイダー）を記述する 1 つの YAML ファイルに置き換えます。スキーマは 2026 年に安定版に達したため、それを中心に設計しても安全です。個々の SDK のサポートはまだ不均一なので、導入する前に、ステータスのセクションをお読みください。

有効にする

ファイルを保存し、1 つの環境変数で SDK をそれに向けます。

export OTEL_CONFIG_FILE=/etc/otel/otel-config.yaml

OTEL_CONFIG_FILE が設定されていると、宣言的な設定をサポートする SDK は、ファイルから自分自身を構築します。その後、他の OTEL_* 変数は、下で説明するようにファイルが参照しない限り、無視されます。

完全な例

otel-config.yaml:

file_format: "1.2"

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
  detection/development:
    detectors:
      - service:
      - host:
      - process:
      - container:

propagator:
  composite:
    - tracecontext:
    - baggage:

tracer_provider:
  sampler:
    parent_based:
      root:
        always_on:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/traces

meter_provider:
  readers:
    - periodic:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/metrics

logger_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT:-http://localhost:4318}/v1/logs

file_format の値には、お使いの SDK のドキュメントが指定するものを使ってください。SDK は、新しいスキーマのバージョンを、それぞれ異なる時期に採用するからです。ファイルの読み方：

• resource は、サービスを記述します。attributes_list は、通常の key=value,key=value の文字列を取り、detectors は、ホスト、プロセス、コンテナの情報を自動的に追加します。/development で終わるプロパティは、まだ実験的であり、すべての SDK に存在するとは限りません。
• propagator は、コンテキストのプロパゲーターを列挙します。ここでは、W3C の trace context と baggage です。
• tracer_provider は、サンプラーとスパンのプロセッサーを保持します。ここでは、バッチプロセッサーが、OTLP HTTP exporter でスパンを送ります。
• meter_provider は、メトリクスのリーダーを保持します。periodic のリーダーは、一定の間隔でエクスポートします。
• logger_provider は、ログに対して同じことを行います。
• otlp_http と otlp_grpc：プロトコルを切り替えるには、exporter の名前とエンドポイントを入れ替えます（gRPC では http://localhost:4317）。

環境変数の置換

ファイル内では、${VAR} が環境変数を読み取り、${VAR:-default} は、未設定のときのデフォルトを提供します。それ以外では、環境変数は無視されます。それが要点で、ファイルが要求しない限り、何も動作を変えません。これにより、環境ごとに何が設定可能かが分かりやすくなります。

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}

tracer_provider:
  processors:
    - batch:
        exporter:
          otlp_http:
            endpoint: ${OTEL_EXPORTER_OTLP_TRACES_ENDPOINT:-http://localhost:4318/v1/traces}

同じファイルが、開発（デフォルト）と本番（プラットフォームが変数を設定）の両方で機能します。

シグナルごとの宛先と、より豊かな構成

宣言的な設定が優れているのは、同じスパンを 2 か所に送る、processor を調整するなど、環境変数ではうまく表現できないことです。

tracer_provider:
  processors:
    - batch:
        schedule_delay: 2000
        max_queue_size: 4096
        exporter:
          otlp_http:
            endpoint: http://collector:4318/v1/traces
    - simple:
        exporter:
          console:

ここでは、スパンがバッチで Collector に送られ、コンソールにも出力されます。これはローカルでのデバッグに便利です。サポートされる processor、sampler、exporter は実装によって異なるため、SDK がサポートする正確なプロパティ名は、お使いの SDK のドキュメントを確認してください。

どの言語がサポートしているか

仕様とスキーマは安定していますが、各言語は、それぞれのスケジュールで実装しています。

• 利用可能： C++、Go、Java、JavaScript、PHP に実装があり、Java エージェントは、独自のセットアップを文書化しています。
• 開発中： .NET と Python。
• ドキュメントは、実装全体のサポートを、依然として実験的と説明しているため、この機能に依存する前に、お使いの言語向けにテストしてください。
• Collector 自体も、内部のテレメトリを設定するために、Go の実装を使っています。

お使いの言語がまだ対応していない場合は、環境変数を使い続けてください。2 つのモデルは、意図的に互換性があります。置換の例で示した変数名は、ファイルなしで使うものと同じです。

2 つの間の選択

環境変数を使う場合	宣言的なファイルを使う場合
サービスごとに少数のオプションを設定する	複数の exporter や processor が必要
プラットフォームがすでに環境を注入している（Operator、Helm）	SDK 全体の設定を 1 つのファイルでレビューしたい
お使いの言語の宣言的サポートがないか、未成熟	複数の言語で同じ設定形式を使いたい

妥当なハイブリッドは、ConfigMap から共有のファイルをマウントし、環境ごとの値だけを、${...} の置換で環境変数に供給させる方法です。

ファイルを配信する

Docker Compose：

services:
  checkout:
    image: myorg/checkout:1.4.2
    environment:
      OTEL_CONFIG_FILE: /etc/otel/otel-config.yaml
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_RESOURCE_ATTRIBUTES: service.version=1.4.2,deployment.environment.name=staging
    volumes:
      - ./otel-config.yaml:/etc/otel/otel-config.yaml:ro

Kubernetes：ファイルを ConfigMap に入れ、マウントして、Deployment で OTEL_CONFIG_FILE を設定します。Git での ConfigMap の変更は、他の変更と同様にロールアウトされますが、SDK は起動時にファイルを読み取るため、Pod を再起動して取り込んでください。

落とし穴

• ファイルのミスで、SDK がプロバイダーを起動できなくなる可能性があります。本番前の環境でテストし、起動時の SDK のログ出力を確認してください（一時的に OTEL_LOG_LEVEL=debug）。
• ファイルに、シークレットを直接入れないでください。${VAR} を使い、Secret から値を注入します。
• 実行時の動的な再構成は、まだこの仕様の一部ではありません。ファイルの変更には再起動が必要です。
• 個々の環境変数の一部は、うまく相互運用できないため、非推奨にする予定ですが、非推奨は削除を意味しません。

完全なスキーマと言語ごとの注意については、宣言的な設定のドキュメントを参照してください。