OpenTelemetry-SDKs teilen sich einen gemeinsamen Satz von Umgebungsvariablen, sodass dieselbe Konfiguration für Java, Python, Node.js, .NET und andere funktioniert. Das ist der gängigste Weg, eine Anwendung zu konfigurieren, und er passt perfekt zu Containern und Kubernetes, da die Plattform die Umgebung setzt. Diese Anleitung behandelt die Variablen, die du am häufigsten nutzen wirst.

Jedes Sprach-SDK setzt die Spezifikation in eigenem Tempo um, verifiziere also weniger gängige Variablen in der Dokumentation deiner Sprache.

Das Wesentliche

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 setzt service.name, das wichtigste Attribut, weil Backends alles danach gruppieren. Ist es nicht gesetzt, bekommst du einen Namen unknown_service. Es hat Vorrang vor service.name innerhalb von OTEL_RESOURCE_ATTRIBUTES.
• OTEL_RESOURCE_ATTRIBUTES ist eine kommagetrennte Liste von key=value-Paaren, die den Service beschreiben, etwa seine Version und Umgebung.
• OTEL_EXPORTER_OTLP_ENDPOINT ist der Ort, an den Telemetrie geht. Richte ihn auf einen Collector.
• OTEL_EXPORTER_OTLP_PROTOCOL ist grpc, http/protobuf oder http/json.

Endpunkte und Protokolle: der Port muss passen

Die Standards sind http://localhost:4318 für HTTP und http://localhost:4317 für gRPC. Bei den HTTP-Protokollen hängt das SDK v1/traces, v1/metrics und v1/logs an den Basis-Endpunkt an. Setzt du einen Endpunkt pro Signal, etwa OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, wird er genau so verwendet, wie er angegeben ist, ohne dass etwas angehängt wird.

Der häufigste Fehler ist eine Abweichung: gRPC an Port 4318 oder HTTP an Port 4317 zu senden. Wähle Protokoll und Port gemeinsam. Das Standardprotokoll in der Spezifikation ist http/protobuf, aber manche SDKs nutzen standardmäßig gRPC, setze es also explizit.

Exporter-Auswahl

export OTEL_TRACES_EXPORTER=otlp      # Standard
export OTEL_METRICS_EXPORTER=otlp     # Standard
export OTEL_LOGS_EXPORTER=otlp        # Standard

Werte sind unter anderem otlp, console (ins Terminal ausgeben, praktisch zum Debuggen) und none, um ein Signal abzuschalten. Manche Sprachen unterstützen weitere, etwa prometheus für Metriken oder zipkin für Traces.

OTLP-Exporter-Optionen

export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer abc123,x-tenant=team-a"
export OTEL_EXPORTER_OTLP_TIMEOUT=10000       # Millisekunden in den meisten SDKs
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

Jede davon hat Varianten pro Signal, etwa OTEL_EXPORTER_OTLP_TRACES_TIMEOUT oder OTEL_EXPORTER_OTLP_METRICS_ENDPOINT, die Vorrang vor der Basisvariable haben. HEADERS ist eine kommagetrennte Liste von key=value-Paaren, und alle Werte sind Strings. Nutze einen https://-Endpunkt für TLS und die Zertifikatsvariablen für private Zertifizierungsstellen oder Mutual TLS.

Propagation und Sampling

export OTEL_PROPAGATORS=tracecontext,baggage    # Standard
export OTEL_TRACES_SAMPLER=parentbased_traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1

• OTEL_PROPAGATORS bestimmt, welche Header Trace-Kontext zwischen Services tragen. Der Standard ist tracecontext,baggage (W3C). Alle Services in einem Anfragepfad müssen kompatible Propagatoren nutzen, sonst reißen Traces an der Grenze ab. Füge b3 oder andere nur hinzu, wenn du mit älteren Systemen interagieren musst.
• OTEL_TRACES_SAMPLER ist standardmäßig parentbased_always_on, was alles aufzeichnet und der Entscheidung des Aufrufers folgt. Für Head Sampling behält parentbased_traceidratio mit OTEL_TRACES_SAMPLER_ARG=0.1 etwa zehn Prozent neuer Traces und respektiert dabei die Entscheidung eines Parents. Die Sampling-Anleitung behandelt, wann stattdessen im Collector gesampelt wird.

Batching und Limits

Batch-Einstellungen steuern Speichernutzung und Exporthäufigkeit. Standardwerte aus der Spezifikation:

Variable	Standard
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 ist der Span-Batch-Prozessor und BLRP der Log-Record-Batch-Prozessor. Erhöhe die Queue-Größe, wenn du unter Last verworfene Spans siehst, und senke das Metrik-Intervall beim Testen (zum Beispiel 10000), damit du nicht eine Minute auf einen Datenpunkt wartest.

Betriebliche Schalter

export OTEL_SDK_DISABLED=true     # Telemetrie abschalten, ohne die Instrumentierung zu entfernen
export OTEL_LOG_LEVEL=debug       # das eigene Diagnose-Log-Level des SDK (Standard info)

OTEL_SDK_DISABLED ist ein schneller Kill-Switch. Debug-Logging ist ausführlich, lass es also in der Produktion nicht an.

In Docker Compose und Kubernetes ablegen

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

Die Operator-Anleitung zeigt, wie du diese automatisch mit einer Instrumentation-Ressource injizierst, damit Anwendungsteams sie nicht von Hand setzen müssen.

Rangfolge und Fallstricke

• Konfiguration im Code gewinnt meist gegen Umgebungsvariablen, und Variablen pro Signal gewinnen gegen allgemeine.
• Eine Variable, die dein SDK nicht erkennt, wird stillschweigend ignoriert. Prüfe die Konfigurationsseite der Sprache, wenn eine Einstellung scheinbar nichts bewirkt.
• Lege keine Secrets in OTEL_RESOURCE_ATTRIBUTES. Es wird zu einem Label an jedem Stück Telemetrie.
• Enthält ein Endpunkt einen Pfad (zum Beispiel hinter einem Proxy), nutze die Endpunktvariablen pro Signal, damit nichts angehängt wird.
• Halte die Variablenliste pro Service an einem Ort (einer Compose-Datei oder einer Helm-Values-Datei), damit Änderungen geprüft werden.

Die vollständige Liste findest du in der Spezifikation der SDK-Umgebungsvariablen und der OTLP-Exporter-Konfiguration.