Zum Inhalt springen
Trainingslager IT-Trainingslager

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 --wait

Erwartet (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 --wait

Erwartet (gekürzt):

"open-telemetry" has been added to your repositories
...
NAME: otel
NAMESPACE: monitoring
STATUS: deployed
  • image: otel/opentelemetry-collector-k8s ist 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.kubernetesAttributes aktiviert den Processor k8s_attributes samt 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. null entfernt sie. Übrig bleibt otlp auf Port 4317 (gRPC) und 4318 (HTTP).
  • Der Collector hat eigene Metriken auf Port 8888. metrics: {enabled: true} macht den Port am Service auf, serviceMonitor.enabled legt den ServiceMonitor dafür an. Wer Signale weiterreicht, muss selbst beobachtet werden.
  • memory_limiter schützt den Collector vor dem Speichertod, batch sammelt Daten und schickt sie gebündelt. Beide gehören in jede Pipeline.
  • Die Exporter heißen nach dem Protokoll: otlp_http/loki ist ein OTLP-Exporter über HTTP, /loki sein 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 3

Erwartet (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 -i startet 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 -1

Erwartet:

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 -13

Erwartet (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.name setzt die Anwendung selbst, den Rest hat der Collector angehängt – auch service.namespace, service.instance.id und service.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 --wait

Erwartet (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 Pod telemetrygen selbst auf die Konsole schreibt – die holt Alloy ab, und Loki leitet auch für sie service_name="telemetrygen" ab.
  • Bei OTLP gibt es keinen Alloy, der Labels setzt. Loki macht aus einigen Resource Attributes selbst Labels: service.name wird zu service_name, k8s.namespace.name zu k8s_namespace_name.
  • Alles andere legt Loki als Structured Metadata neben die Zeile.
logcli labels --quiet --since 5m | grep k8s

Erwartet (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.namespace und service.name wird job, aus service.instance.id wird instance – so passen OTLP-Metriken zu den gescrapten.
  • telemetrygen zä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 2

Nach 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.