Tag 9: Der OpenTelemetry Collector
Ziel: Ein Collector nimmt Traces, Logs und Metriken per OTLP an, reichert sie mit Kubernetes-Daten an und verteilt sie an die richtigen Ziele. · Dauer: ca. 75 min · Voraussetzung: Tag 8
Briefing
- OpenTelemetry (OTel) ist ein offener Standard für alle drei Signale: eine API für den Code, SDKs für viele Sprachen und ein Protokoll für den Transport, OTLP.
- Der Collector ist ein eigenständiger Dienst dazwischen. Anwendungen schicken alles an ihn, er entscheidet, wohin es geht. Wechselst du das Backend, ändert sich nur der Collector, nicht jede Anwendung.
- Eine Konfiguration besteht aus Receivern (wie kommt es rein), Processors (was passiert unterwegs) und Exportern (wohin geht es). Pipelines verbinden sie, eine pro Signal.
- Heute füttert ein Testgenerator den Collector. An Tag 10 schickt notes-api selbst.
telemetrygen ── OTLP ──► Collector ── traces ──► debug (Log des Collectors)
receivers logs ────► Loki (/otlp)
processors metrics ─► Prometheus (/api/v1/otlp)
Drill 1: Prometheus nimmt OTLP an
Prometheus 3 kann Metriken nicht nur abholen, sondern auch per OTLP
empfangen. Der Operator schaltet das mit einer Zeile ein – hier die
ganze kps.yaml:
cd ~/obs-lab
cat > kps.yaml <<'EOF'
fullnameOverride: kps
prometheus:
service:
type: NodePort
nodePort: 30090
prometheusSpec:
serviceMonitorSelectorNilUsesHelmValues: false
ruleSelectorNilUsesHelmValues: false
enableOTLPReceiver: true
retention: 3d
resources:
requests: {cpu: 100m, memory: 300Mi}
limits: {memory: 800Mi}
alertmanager:
service:
type: NodePort
nodePort: 30093
config:
route:
receiver: echo
group_by: [alertname, namespace]
group_wait: 30s
group_interval: 2m
repeat_interval: 4h
routes:
- receiver: "null"
matchers: [alertname = "Watchdog"]
receivers:
- name: "null"
- name: echo
webhook_configs:
- url: http://alarm-echo.monitoring:8080/
grafana:
adminPassword: lab-grafana-pw-123
service:
type: NodePort
nodePort: 30300
kubeControllerManager: {enabled: false}
kubeScheduler: {enabled: false}
kubeProxy: {enabled: false}
kubeEtcd: {enabled: false}
EOF
helm upgrade kps prometheus-community/kube-prometheus-stack --version 92.18.0 \
-n monitoring -f kps.yaml --waitErwartet (gekürzt):
Release "kps" has been upgraded. Happy Helming!
...
REVISION: 3
Neu ist nur enableOTLPReceiver: true. Prüfe, ob
Prometheus mit dem Schalter läuft:
kubectl -n monitoring get prometheus kps-prometheus \
-o jsonpath='{.spec.enableOTLPReceiver}{"\n"}'Erwartet:
true
Fortschritt speichern? Kostenlos registrieren
Drill 2: Der Collector
helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts
helm repo update open-telemetry
cat > otel.yaml <<'EOF'
mode: deployment
fullnameOverride: otel-collector
image:
repository: otel/opentelemetry-collector-k8s
presets:
kubernetesAttributes:
enabled: true
resources:
requests: {cpu: 20m, memory: 64Mi}
limits: {memory: 256Mi}
ports:
jaeger-compact: {enabled: false}
jaeger-thrift: {enabled: false}
jaeger-grpc: {enabled: false}
zipkin: {enabled: false}
metrics: {enabled: true}
serviceMonitor:
enabled: true
config:
receivers:
jaeger: null
zipkin: null
prometheus: null
exporters:
debug:
verbosity: basic
otlp_http/loki:
endpoint: http://loki:3100/otlp
otlp_http/prometheus:
endpoint: http://kps-prometheus:9090/api/v1/otlp
service:
pipelines:
traces:
receivers: [otlp]
processors: [memory_limiter, k8s_attributes, batch]
exporters: [debug]
logs:
receivers: [otlp]
processors: [memory_limiter, k8s_attributes, batch]
exporters: [otlp_http/loki]
metrics:
receivers: [otlp]
processors: [memory_limiter, k8s_attributes, batch]
exporters: [otlp_http/prometheus]
EOF
helm install otel open-telemetry/opentelemetry-collector --version 0.178.2 \
-n monitoring -f otel.yaml --waitErwartet (gekürzt):
"open-telemetry" has been added to your repositories
...
NAME: otel
NAMESPACE: monitoring
STATUS: deployed
image: otel/opentelemetry-collector-k8sist die Distribution des Collectors für Kubernetes: nur die Bausteine, die man dort braucht. Das Chart verlangt, dass du eine Distribution ausdrücklich wählst.presets.kubernetesAttributesaktiviert den Processork8s_attributessamt Rechten. Er schaut nach, von welchem Pod ein Signal kommt, und hängt Namespace, Pod und Deployment an.- Das Chart bringt Receiver für Jaeger, Zipkin und Prometheus mit.
nullentfernt sie. Übrig bleibtotlpauf Port 4317 (gRPC) und 4318 (HTTP). - Der Collector hat eigene Metriken auf Port 8888.
metrics: {enabled: true}macht den Port am Service auf,serviceMonitor.enabledlegt den ServiceMonitor dafür an. Wer Signale weiterreicht, muss selbst beobachtet werden. memory_limiterschützt den Collector vor dem Speichertod,batchsammelt Daten und schickt sie gebündelt. Beide gehören in jede Pipeline.- Die Exporter heißen nach dem Protokoll:
otlp_http/lokiist ein OTLP-Exporter über HTTP,/lokisein frei gewählter Name. Loki und Prometheus sprechen OTLP selbst – kein Umweg über eigene Formate.
kubectl -n monitoring logs deploy/otel-collector | grep -m1 "Everything is ready"Erwartet:
2026-11-05T09:25:01.552Z info [email protected]/service.go:256 Everything is ready...
Fortschritt speichern? Kostenlos registrieren
Drill 3: Traces aus dem Generator
telemetrygen ist ein Testwerkzeug aus dem
OpenTelemetry-Projekt. Es erzeugt Signale auf Bestellung:
kubectl -n app run telemetrygen --rm -i --restart=Never \
--image ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.163.0 \
-- traces --otlp-endpoint otel-collector.monitoring:4317 --otlp-insecure --traces 3Erwartet (gekürzt):
...
2026-11-05T09:25:50.000Z INFO traces/worker.go:180 traces generated {"worker": 0,...
2026-11-05T09:25:50.001Z INFO traces/traces.go:75 stop the batch span processor
...
pod "telemetrygen" deleted from app namespace
Dazwischen protokolliert der gRPC-Client jeden Schritt seiner
Verbindung. Wichtig ist nur die Zeile traces generated.
kubectl run --rm -istartet einen Pod, zeigt seine Ausgabe und löscht ihn danach.--otlp-insecure: Im Cluster ohne TLS.
Der Exporter debug schreibt, was ankommt, ins Log des
Collectors:
kubectl -n monitoring logs deploy/otel-collector | grep Traces | tail -1Erwartet:
2026-11-05T09:25:50.170Z info Traces {"resource": {...}, "resource spans": 1, "spa...
Drei Traces mit je zwei Spans: Jeder Trace von telemetrygen besteht aus einem Span „lets-go“ und einem Kind-Span „okey-dokey“.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Was k8s_attributes anhängt
Stelle debug kurz auf ausführlich:
helm upgrade otel open-telemetry/opentelemetry-collector --version 0.178.2 \
-n monitoring -f otel.yaml --set config.exporters.debug.verbosity=detailed --wait
kubectl -n app run telemetrygen --rm -i --restart=Never \
--image ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.163.0 \
-- traces --otlp-endpoint otel-collector.monitoring:4317 --otlp-insecure --traces 1
kubectl -n monitoring logs deploy/otel-collector \
| grep -A12 "Resource attributes" | tail -13Erwartet (gekürzt):
Resource attributes:
-> service.name: Str(telemetrygen)
-> k8s.namespace.name: Str(app)
-> service.namespace: Str(app)
-> k8s.pod.start_time: Str(2026-11-05T09:29:25Z)
-> k8s.pod.uid: Str(56535107-e67c-464c-9ad9-9991cd215909)
-> k8s.node.name: Str(obs)
-> k8s.cluster.uid: Str(ce67563c-57a5-4453-a428-680e86171291)
-> k8s.pod.name: Str(telemetrygen)
-> k8s.container.name: Str(telemetrygen)
-> container.image.name: Str(ghcr.io/open-telemetry/opentelemetry-collector-co...
-> service.instance.id: Str(app.telemetrygen.telemetrygen)
-> service.version: Str(v0.163.0)
- Resource Attributes beschreiben, wer ein
Signal erzeugt hat.
service.namesetzt die Anwendung selbst, den Rest hat der Collector angehängt – auchservice.namespace,service.instance.idundservice.version, die er aus Pod und Image ableitet. - Er findet den Pod über die IP-Adresse der eingehenden Verbindung und fragt die Kubernetes-API nach dem Rest.
--set gilt nur für diesen Aufruf. Zurück auf knapp:
helm upgrade otel open-telemetry/opentelemetry-collector --version 0.178.2 \
-n monitoring -f otel.yaml --waitErwartet (letzte Zeilen gekürzt):
Release "otel" has been upgraded. Happy Helming!
...
REVISION: 3
Fortschritt speichern? Kostenlos registrieren
Drill 5: Logs und Metriken
kubectl -n app run telemetrygen --rm -i --restart=Never \
--image ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.163.0 \
-- logs --otlp-endpoint otel-collector.monitoring:4317 --otlp-insecure --logs 5 \
--body "Hallo aus OTLP"
logcli query --quiet --limit 2 -o raw \
'{service_name="telemetrygen", service_namespace="app"}'Erwartet:
Hallo aus OTLP
Hallo aus OTLP
- Die Abfrage braucht
service_namespace="app". Ohne dieses Label kämen auch die Zeilen, die der Podtelemetrygenselbst auf die Konsole schreibt – die holt Alloy ab, und Loki leitet auch für sieservice_name="telemetrygen"ab. - Bei OTLP gibt es keinen Alloy, der Labels setzt. Loki macht aus
einigen Resource Attributes selbst Labels:
service.namewird zuservice_name,k8s.namespace.namezuk8s_namespace_name. - Alles andere legt Loki als Structured Metadata neben die Zeile.
logcli labels --quiet --since 5m | grep k8sErwartet (gekürzt):
k8s_namespace_name
k8s_pod_name
...
Jetzt Metriken:
kubectl -n app run telemetrygen --rm -i --restart=Never \
--image ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.163.0 \
-- metrics --otlp-endpoint otel-collector.monitoring:4317 --otlp-insecure \
--metrics 10 --otlp-metric-name lab_demo
promtool query instant http://localhost:30090 'lab_demo'Erwartet (gekürzt):
lab_demo{instance="app.telemetrygen.telemetrygen", job="app/telemetrygen"} => 9 @[...]
- Prometheus hat die Metrik nicht gescrapt, der Collector hat sie
geschickt. Aus
service.namespaceundservice.namewirdjob, ausservice.instance.idwirdinstance– so passen OTLP-Metriken zu den gescrapten. telemetrygenzählt einen Gauge hoch. Der letzte Wert ist 9: zehn Werte, ab 0.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Wie viele Logzeilen hat der Collector angenommen?
promtool query instant http://localhost:30090 'otelcol_receiver_accepted_log_records'Erwartet (gekürzt):
otelcol_receiver_accepted_log_records{..., receiver="otlp", transport="grpc"} => 5 @[...
Die fünf Zeilen aus Drill 5. Die Spans aus Drill 3 und 4 zählt der
Collector nicht mehr: helm upgrade hat seinen Pod ersetzt,
und die Zähler begannen bei 0. Diese Metrik hat Prometheus über den
ServiceMonitor des Charts gescrapt.
kubectl -n monitoring get svc otel-collector -o jsonpath='{.spec.ports[*].port}{"\n"}'Erwartet:
8888 4317 4318
4317 für OTLP über gRPC, 4318 für OTLP über HTTP, 8888 für die eigenen Metriken. notes-api wird an Tag 10 Port 4318 nutzen.
Challenge
Schicke zwei Traces über HTTP statt gRPC und zeige mit einer Abfrage auf die Metriken des Collectors, dass sie angekommen sind.
Hinweis: telemetrygen traces --help
kennt eine Option für HTTP. Der Port ist ein anderer. Die Metrik heißt
wie im Kontrollpunkt, nur mit spans statt
log_records.
Lösung
kubectl -n app run telemetrygen --rm -i --restart=Never \
--image ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.163.0 \
-- traces --otlp-endpoint otel-collector.monitoring:4318 --otlp-insecure \
--otlp-http --traces 2Nach einer halben Minute:
promtool query instant http://localhost:30090 \
'sum by (transport) (otelcol_receiver_accepted_spans)'Erwartet:
{transport="http"} => 4 @[...]
Zwei Traces mit je zwei Spans, alle über HTTP.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Agent und Gateway: Im Betrieb läuft oft ein Collector pro Knoten (DaemonSet, „Agent“) und dahinter ein zentraler („Gateway“) für Sampling, Filter und Ziele. Der Agent bleibt einfach, das Gateway trägt die Logik.
- Eigene Distribution: Mit dem OpenTelemetry
Collector Builder (
ocb) baust du einen Collector nur mit den Bausteinen, die du brauchst. Weniger Code, weniger Angriffsfläche. - Senden statt Scrapen: Kurzlebige Jobs, Funktionen und Geräte außerhalb des Clusters kann Prometheus nicht scrapen. Für sie ist OTLP an den Collector der Weg.