Umgebungsvariablen funktionieren gut für eine Handvoll Einstellungen, werden aber unhandlich, wenn du mehrere Exporter, eigene Prozessoren oder Sampling-Regeln brauchst. Deklarative Konfiguration ersetzt sie durch eine einzelne YAML-Datei, die das gesamte SDK beschreibt: Resource, Propagatoren und die Provider für Tracer, Meter und Logger. Das Schema erreichte 2026 ein stabiles Release, was bedeutet, dass du bedenkenlos darum herum planen kannst. Die Unterstützung in einzelnen SDKs ist noch uneinheitlich, lies also den Statusabschnitt, bevor du dich dafür entscheidest.

Einschalten

Speichere eine Datei und richte das SDK mit einer Umgebungsvariable darauf:

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

Ist OTEL_CONFIG_FILE gesetzt, baut sich ein SDK mit Unterstützung für deklarative Konfiguration aus der Datei auf. Andere OTEL_*-Variablen werden dann ignoriert, es sei denn, die Datei referenziert sie, wie unten beschrieben.

Ein vollständiges Beispiel

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

Nutze den file_format-Wert, den die Dokumentation deines SDKs vorgibt, da SDKs neue Schema-Versionen zu unterschiedlichen Zeiten übernehmen. So liest du die Datei:

• resource beschreibt den Service. attributes_list nimmt den üblichen String key=value,key=value, und detectors fügen automatisch Host-, Prozess- und Container-Informationen hinzu. Eigenschaften, die auf /development enden, sind noch experimentell und existieren womöglich nicht in jedem SDK.
• propagator listet die Kontext-Propagatoren auf, hier W3C Trace Context und Baggage.
• tracer_provider enthält den Sampler und die Span-Prozessoren. Hier sendet ein Batch-Prozessor Spans über einen OTLP-HTTP-Exporter.
• meter_provider enthält Metrik-Reader. Ein periodic-Reader exportiert in einem Intervall.
• logger_provider tut dasselbe für Logs.
• otlp_http vs. otlp_grpc: Tausche Exportername und Endpunkt aus (http://localhost:4317 für gRPC), um Protokolle zu wechseln.

Substitution von Umgebungsvariablen

Innerhalb der Datei liest ${VAR} eine Umgebungsvariable und ${VAR:-default} liefert einen Standardwert, wenn sie nicht gesetzt ist. Umgebungsvariablen werden sonst ignoriert, und genau das ist der Punkt: Nichts ändert das Verhalten, wenn die Datei nicht danach fragt. Das macht leicht sichtbar, was pro Umgebung konfigurierbar ist:

resource:
  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}

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

Dieselbe Datei funktioniert dann in der Entwicklung (Standardwerte) und der Produktion (die Plattform setzt die Variablen).

Ziele pro Signal und reichhaltigere Setups

Deklarative Konfiguration glänzt bei Dingen, die Umgebungsvariablen nicht gut ausdrücken können, etwa dieselben Spans an zwei Orte zu senden oder einen Prozessor abzustimmen:

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

Hier gehen Spans in Batches an einen Collector und werden zusätzlich auf der Konsole ausgegeben, was zum lokalen Debuggen nützlich ist. Prüfe die Dokumentation deines SDKs auf die exakten Eigenschaftsnamen, die es unterstützt, da die verfügbaren Prozessoren, Sampler und Exporter von der Implementierung abhängen.

Welche Sprachen es unterstützen

Die Spezifikation und das Schema sind stabil, aber jede Sprache setzt sie nach eigenem Zeitplan um:

• Verfügbar: C++, Go, Java, JavaScript und PHP haben Implementierungen, und der Java-Agent dokumentiert sein eigenes Setup.
• In Entwicklung: .NET und Python.
• Die Dokumentation beschreibt die Unterstützung über Implementierungen hinweg weiterhin als experimentell, behandle das Feature also als eines, das du für deine Sprache testen solltest, bevor du dich darauf verlässt.
• Der Collector selbst nutzt die Go-Implementierung, um seine interne Telemetrie zu konfigurieren.

Ist deine Sprache noch nicht so weit, nutze weiter Umgebungsvariablen. Die beiden Modelle sind absichtlich kompatibel: Die Variablennamen in den Substitutionsbeispielen sind dieselben, die du ohne Datei verwenden würdest.

Zwischen beiden wählen

Nutze Umgebungsvariablen, wenn	Nutze eine deklarative Datei, wenn
Du pro Service wenige Optionen setzt	Du mehrere Exporter oder Prozessoren brauchst
Deine Plattform die Umgebung bereits injiziert (Operator, Helm)	Du das gesamte SDK-Setup in einer Datei geprüft haben willst
Die deklarative Unterstützung deiner Sprache fehlt oder unreif ist	Du dasselbe Konfigurationsformat über mehrere Sprachen willst

Ein vernünftiger Hybrid ist, eine gemeinsame Datei aus einer ConfigMap zu mounten und Umgebungsvariablen nur die Werte pro Umgebung über ${...}-Substitution liefern zu lassen.

Die Datei ausliefern

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: Lege die Datei in eine ConfigMap, mounte sie und setze OTEL_CONFIG_FILE im Deployment. Eine Änderung an der ConfigMap in Git rollt dann wie jede andere Änderung aus, aber SDKs lesen die Datei beim Start, starte die Pods also neu, um sie aufzugreifen.

Fallstricke

• Ein Fehler in der Datei kann das SDK daran hindern, seine Provider zu starten. Teste sie in einer Vorproduktionsumgebung und beobachte die eigene Log-Ausgabe des SDKs beim Start (OTEL_LOG_LEVEL=debug vorübergehend).
• Lege keine Secrets direkt in die Datei. Nutze ${VAR} und injiziere den Wert aus einem Secret.
• Dynamische Rekonfiguration zur Laufzeit ist noch nicht Teil dieser Spezifikation. Die Datei zu ändern erfordert einen Neustart.
• Einige einzelne Umgebungsvariablen sind zur Veraltung vorgesehen, weil sie nicht gut interoperieren, aber veraltet bedeutet nicht entfernt.

Das vollständige Schema und Hinweise pro Sprache findest du in der Dokumentation zur deklarativen Konfiguration.