# OpenTelemetry in Kubernetes: Architektur & Setup für Distributed Tracing

OpenTelemetry (OTel) in Kubernetes ist ein Cloud-Native-Framework zur herstellerneutralen Erfassung von Traces, Metriken und Logs. Über K8s-Operatoren und den OTel Collector ermöglicht es die automatische Instrumentierung sowie den Telemetrie-Export via OTLP an verteilte Backends, ohne den Anwendungscode anzupassen.

### Zusammenfassung

- OpenTelemetry erfasst in Kubernetes Traces, Metriken und Logs herstellerneutral und exportiert sie per OTLP.
- Zusammenhängende Traces entstehen nur, wenn alle beteiligten Services den Trace Context korrekt weitergeben.
- Der Collector läuft als DaemonSet, als zentrales Gateway oder als Kombination aus beidem.
- Der OpenTelemetry Operator ergänzt neue Pods per Annotation um die automatische Instrumentierung.
- Der Kubernetes Attributes Processor ordnet Spans Namespace, Pod und Deployment zu.
- Head- und Tail-Sampling sowie Filter- und Redaction-Prozessoren steuern Datenmenge und sensible Inhalte.

## Was leistet OpenTelemetry in Kubernetes?

Die automatische Erfassung ohne Quellcodeänderungen gilt für unterstützte Laufzeiten und Bibliotheken. Dafür müssen Instrumentierung und Deployment eingerichtet werden. Eigene Geschäftsoperationen benötigen gegebenenfalls zusätzliche Spans im Anwendungscode. Der OpenTelemetry Operator ist außerdem eine mögliche Betriebsform, keine zwingende Voraussetzung für jede OTel-Installation. Auch ohne Operator lassen sich SDKs und Collector betreiben.

Reine Metriken zeigen beispielsweise, dass die Antwortzeit eines Services steigt. Sie rekonstruieren aber nicht automatisch den Weg einer konkreten Anfrage durch eine [Microservice-Architektur](https://www.ionos.de/digitalguide/websites/web-entwicklung/microservice-architecture-so-funktionieren-microservices/). Ein **Trace** verbindet die Operationen dieser Anfrage. Jeder **Span** beschreibt einen einzelnen Abschnitt mit Zeitinformationen und Attributen. Der Trace wird erst vollständig, wenn die beteiligten Services den Kontext korrekt weitergeben.

**Context Propagation** überträgt unter anderem Trace-ID und Elternbeziehung über Prozessgrenzen. Für HTTP wird dafür häufig W3C Trace Context verwendet. OTLP erfüllt eine andere Aufgabe: Das Protokoll transportiert die erzeugte Telemetrie zum Collector oder Backend. Ein erreichbarer OTLP-Endpunkt beweist daher noch nicht, dass ein zusammenhängender Trace entsteht. Prüfen Sie zunächst einen Request über mindestens zwei Services.

## Wie wählen Sie das Collector-Deployment?

Ein OpenTelemetry Collector lässt sich lokal oder zentral bereitstellen. Die Auswahl richtet sich nach der Datenquelle und dem erforderlichen Verarbeitungszustand. Node-Dateien erfordern einen lokalen Zugriff. Eine Tail-Sampling-Entscheidung benötigt dagegen die zusammengehörigen Spans mehrerer Services. Zusätzliche Collector-Ebenen sollten einen solchen konkreten Bedarf erfüllen, weil sie Ressourcen verbrauchen und einen weiteren Transportabschnitt einführen.

- **DaemonSet auf Node-Ebene:** Geeignet für Host-Metriken und Container-Logs mit lokalem Zugriff. Ein schlank konfigurierter Agent übernimmt zusätzlich Metadatenanreicherung und Weiterleitung. Der Ressourcenbedarf wächst mit der Node-Zahl; ein Node-Ausfall betrifft auch den lokalen Agent.
- **Deployment als Gateway:** Geeignet für zentrale Exportregeln und Backend-Zugangsdaten. Replikate skalieren unabhängig von der Node-Zahl. Tail-Sampling benötigt zusätzlich eine Verteilung nach Trace-ID. Ein Deployment allein erzeugt weder globales Load Balancing noch automatische Ausfallsicherheit.
- **Agent-to-Gateway als Hybrid:** Trennt lokale Erfassung von aufwendiger zentraler Verarbeitung. Agents und Gateways benötigen jeweils passende Ressourcenlimits. Für unabhängige Ausfalldomänen müssen die Gateway-Replikate auf getrennten Nodes liegen und Warteschlangen Störungen zwischen den Ebenen abfedern.

OTLP/gRPC nutzt üblicherweise Port `4317`, OTLP/HTTP Port `4318`. Beide eignen sich für den Telemetrieexport. Wählen Sie die Variante, die SDK, Ingress und Proxy durchgängig unterstützen. Ein Kubernetes-Service stellt den Gateway-Endpunkt bereit. Beachten Sie bei gRPC, dass langlebige Verbindungen die Lastverteilung beeinflussen. TLS und bei Bedarf mTLS sichern die Übertragung, NetworkPolicies beschränken die erlaubten Kommunikationswege.

## Wie instrumentiert der Operator Workloads?

Der [OpenTelemetry Operator](https://opentelemetry.io/docs/platforms/kubernetes/operator/ "OpenTelemetry Operator für Kubernetes") verwaltet Collector-Ressourcen und die automatische Instrumentierung unterstützter Workloads.

Bei einer Installation über das Standardmanifest wird `cert-manager` für die Webhook-Zertifikate benötigt; das Helm-Chart unterstützt alternativ unter anderem die automatische Erzeugung eines selbstsignierten Zertifikats. Für eine Java-Anwendung wird zunächst eine `Instrumentation`-Ressource eingerichtet. Sie legt unter anderem Exportendpunkt und Propagatoren fest. Setzen Sie `spec.exporter.endpoint` explizit auf einen erreichbaren Collector-Service. Ohne diese Angabe verwendet der Operator standardmäßig `http://localhost:4317`, wodurch die Telemetrie in diesem Setup nicht beim zentralen Collector ankommt. Eine Annotation im Pod-Template wählt anschließend die gewünschte `Instrumentation`-Ressource aus. Der Admission-Webhook ergänzt neu erstellte Pods um die Instrumentierung.

Das folgende Beispiel setzt einen installierten Operator und einen erreichbaren Collector-Service `otel-gateway` im Namespace `observability` voraus. Der OTLP/HTTP-Receiver muss nicht nur aktiviert, sondern auch über das Pod-Netzwerk erreichbar sein, beispielsweise mit einem Endpoint wie `0.0.0.0:4318` oder einer passenden Pod-IP. Eine Bindung ausschließlich an `localhost` ist von anderen Pods nicht erreichbar.

```yaml
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
  name: checkout-instrumentation
  namespace: apps
spec:
  exporter:
    endpoint: http://otel-gateway.observability.svc.cluster.local:4318
  propagators:
    - tracecontext
    - baggage
  sampler:
    type: parentbased_traceidratio
    argument: "1"
```

Die Java-Auto-Instrumentierung verwendet standardmäßig OTLP über http/protobuf. Deshalb zeigt das Beispiel auf den OTLP/HTTP-Port 4318 und nicht auf den gRPC-Port 4317.

Der Wert `"1"` dient hier dazu, in einer Testumgebung alle neu begonnenen Root-Traces auszuwählen. Übernommene Sampling-Entscheidungen folgen dem Parent-Kontext. Für den Produktivbetrieb ist die Rate bewusst festzulegen. Das Beispiel nutzt internes HTTP zur Veranschaulichung. Für verschlüsselte Verbindungen müssen Endpunkt und Zertifikatskonfiguration angepasst werden.

Ergänzen Sie im bestehenden Deployment unter `spec.template.metadata.annotations` folgende Annotation. Der Ausschnitt ist kein vollständiges Deployment-Manifest:

```yaml
instrumentation.opentelemetry.io/inject-java: "checkout-instrumentation"
```

Legen Sie die Instrumentation-Ressource vor dem neuen Pod an. Im Beispiel liegt sie im selben Namespace wie die Anwendung. Alternativ kann die Annotation mit namespace/name auf eine Instrumentation-Ressource in einem anderen Namespace verweisen. Nach der Änderung des Pod-Templates erzeugt das Deployment neue Pods. Für andere Sprachen gelten eigene Annotationen und Kompatibilitätsanforderungen. Prüfen Sie anschließend die injizierte Konfiguration, den tatsächlichen Service-Namen und die Erreichbarkeit des Receivers. Sind die beteiligten Services instrumentiert und propagieren sie den Trace Context korrekt, sollten automatisch erzeugte HTTP-Spans einen Testrequest serviceübergreifend sichtbar machen.

### Wie erhalten Spans Kubernetes-Metadaten?

Der Kubernetes Attributes Processor ordnet eingehende Telemetrie einem Pod zu und ergänzt Resource Attributes. Dazu benötigt der Collector passende RBAC-Rechte zum Lesen der relevanten Kubernetes-Ressourcen. Hinter einem Agent oder Proxy sieht ein Gateway möglicherweise nur dessen IP-Adresse. Eine explizit mitgegebene Pod-UID und eine darauf abgestimmte Zuordnungsregel vermeiden dann eine falsche Pod-Zuordnung.

- `k8s_attributes`: Ergänzt etwa Namespace, Pod und Deployment als Resource Attributes. Die Extraktion eigener Labels und Annotationen wird gezielt konfiguriert. Ältere Collector-Versionen und Konfigurationen können noch den Alias `k8sattributes` verwenden.
- Nodebezogene Begrenzung: Im DaemonSet lässt sich die Pod-Erfassung auf den eigenen Node beschränken. Ein zentrales Gateway benötigt dagegen gegebenenfalls einen Cache für Metadaten des gesamten Clusters. Das beeinflusst den Speicherbedarf.

## Wie steuern Sie Sampling und sensible Daten?

**Head-Sampling** entscheidet früh, häufig bereits im SDK. Es senkt den Datenstrom vor dem Collector, kennt aber spätere Fehler eines Requests noch nicht. **Tail-Sampling** berücksichtigt die eintreffenden Spans eines Traces und wählt beispielsweise Fehlerfälle oder langsame Abläufe aus. Was das Head-Sampling bereits verworfen hat, kann das Tail-Sampling nicht nachträglich wiederherstellen.

Für eine verteilte Tail-Sampling-Stufe müssen alle Spans einer Trace-ID beim selben zuständigen Collector eintreffen. Der `load_balancing` Exporter kann dieses Routing anhand der Trace-ID übernehmen. Warten auf Spans benötigt Arbeitsspeicher. Entscheidungswartezeit und Trace-Kapazität sind deshalb anhand der Trace-Dauer und Last zu dimensionieren. Änderungen an der Replikazahl können laufende Zuordnungen beeinflussen.

Wichtige Prozessoren übernehmen dabei unterschiedliche Aufgaben:

- `tail_sampling`: Trifft regelbasierte Entscheidungen über Traces. Kubernetes-Anreicherung muss davor erfolgen, wenn sie den ursprünglichen Empfangskontext benötigt.
- `filter`: Verwirft passende Spans oder andere Telemetrieelemente anhand von Bedingungen. Der Processor entfernt nicht automatisch nur einzelne sensible Felder eines Spans.
- `redaction`: Entfernt nicht zugelassene Attribute und maskiert konfigurierte Werte. Bleibt `allowed_keys` leer und ist `allow_all_keys` nicht aktiviert, entfernt der Processor alle betreffenden Attribute. Soll er alle Attribute behalten und nur bestimmte Werte maskieren, setzen Sie `allow_all_keys: true`. Die Komponente gilt derzeit für Traces als Beta sowie für Logs und Metriken als Alpha.

Erfassen Sie sensible Header und Request-Inhalte möglichst gar nicht erst. Prüfen Sie zusätzlich Span-Namen und Events, damit personenbezogene Informationen nicht über andere Felder exportiert werden. Die Prozessoren unterstützen technische Datenminimierung. Eine vollständige Anonymisierung oder rechtskonforme Gesamtverarbeitung ergibt sich daraus nicht automatisch.

## Wie binden Sie das Backend an?

Das Gateway exportiert an ein OTLP-kompatibles Backend. Das kann ein selbst betriebenes Open-Source-System oder ein herstellerneutral angebundener Managed Service sein. Ein Grafana-Tempo-Backend lässt sich beispielsweise in eine bestehende Analyseoberfläche integrieren. Zentralisieren Sie Backend-Zugangsdaten im Gateway und konfigurieren Sie Export-Queues samt Retries. Prüfen Sie separat, welche Daten bei einem Pod-Neustart tatsächlich persistent bleiben.

Die Korrelation mit Logs benötigt Trace-ID und gegebenenfalls Span-ID im Log-Datensatz. Gemeinsame Service- und Kubernetes-Attribute erleichtern den Wechsel zwischen Signalen. Metrik-Exemplare können auf zugehörige Traces verweisen, wenn Instrumentierung und Backend dies unterstützen. Ein Abnahmetest sollte deshalb nicht nur den Trace zeigen, sondern auch den Sprung zum passenden Log-Eintrag und die korrekte Zuordnung nach einem Pod-Wechsel bestätigen.


This is a markdown version of: [https://www.ionos.de/digitalguide/server/konfiguration/opentelemetry-kubernetes/](https://www.ionos.de/digitalguide/server/konfiguration/opentelemetry-kubernetes/) for AI/LLM consumption.