Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 11: Metriken, Logs und Traces verbinden

Ziel: Von einem Ausreißer im Histogramm zum Trace, vom Trace zu den Logzeilen und zurück – über die Trace-ID, auf der Kommandozeile und mit einem Klick in Grafana. · Dauer: ca. 75 min · Voraussetzung: Tag 10

Briefing

  • Drei Signale sind erst dann mehr als drei Werkzeuge, wenn sie sich gegenseitig finden. Der gemeinsame Schlüssel ist die Trace-ID.
  • Exemplars hängen an einzelne Messwerte eines Histogramms eine Trace-ID. So zeigt ein Graph nicht nur „hier war es langsam“, sondern auch „das war diese Anfrage“. metrics.go setzt sie schon seit Tag 0, nur Prometheus speichert sie noch nicht.
  • logging.go schreibt trace_id in jede Logzeile, sobald eine Anfrage einen Trace hat – seit Tag 10 also immer.
  • Grafana verbindet die Datenquellen über Einstellungen: Exemplars zeigen auf Tempo, Trace-IDs in Logs auch, und Tempo zeigt zurück auf Loki.
 Prometheus ── Exemplar trace_id ──► Tempo ── trace_id ──► Loki
      ▲                                                     │
      └──────────── gleiche Anfrage, drei Blickwinkel ◄──────┘

Drill 1: Trace-IDs in den Logs

kubectl -n app logs deploy/notes-api --tail 1 | jq .

Erwartet (gekürzt):

{
  "time": "2026-11-05T09:42:07.297792269Z",
  "level": "INFO",
  "msg": "request",
  "method": "POST",
  "path": "/notes",
  "status": 201,
  "duration_ms": 2,
  "trace_id": "ab4e8f3c478e0f18e3890987435c9b01",
  "span_id": "1a572cb8efa1dc58"
}

Seit dem Rollout von Tag 10 trägt jede Zeile trace_id und span_id. logging.go holt sie aus dem Kontext der Anfrage, den otelhttp vorbereitet hat.

Merke dir die Trace-ID und suche den Trace in Tempo. Setze deine ID ein:

curl -s localhost:30320/api/v2/traces/ab4e8f3c478e0f18e3890987435c9b01 \
  | jq -r '.trace.resourceSpans[].scopeSpans[].spans[] | [.name, .spanId] | @tsv'

Erwartet:

INSERT  BlcRG3+ammQ=
POST /notes GlcsuO+h3Fg=
  • Derselbe Vorgang, einmal als Logzeile, einmal als Trace. Diesmal war es ein POST, der Span von Postgres heißt darum INSERT.
  • Tempo liefert die Span-IDs in Base64. GlcsuO+h3Fg= ist 1a572cb8efa1dc58 in Hexadezimal – die span_id der Logzeile gehört zum Server-Span.

Und andersherum, vom Trace zu den Logs:

logcli query --quiet -o raw --since 15m \
  '{app="notes-api"} |= "ab4e8f3c478e0f18e3890987435c9b01"'

Erwartet:

{"time":"2026-11-05T09:42:07.297792269Z","level":"INFO","msg":"request","method":"POS...

Der Zeilenfilter |= reicht – eine Trace-ID ist eindeutig genug, kein Parser nötig.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Exemplars speichern

Prometheus speichert Exemplars erst, wenn du es einschaltest. Gleichzeitig bekommt die Datenquelle in Grafana einen Verweis auf Tempo. Beides steht in kps.yaml – hier die ganze Datei:

cd ~/obs-lab
cat > kps.yaml <<'EOF'
fullnameOverride: kps

prometheus:
  service:
    type: NodePort
    nodePort: 30090
  prometheusSpec:
    serviceMonitorSelectorNilUsesHelmValues: false
    ruleSelectorNilUsesHelmValues: false
    enableOTLPReceiver: true
    enableFeatures: [exemplar-storage]
    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
  sidecar:
    datasources:
      exemplarTraceIdDestinations:
        datasourceUid: tempo
        traceIdLabelName: trace_id

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: 4
  • enableFeatures: [exemplar-storage] startet Prometheus mit --enable-feature=exemplar-storage. Exemplars liegen in einem eigenen kleinen Speicher im Arbeitsspeicher, standardmäßig 100 000 Stück.
  • exemplarTraceIdDestinations sagt Grafana: Das Label trace_id an einem Exemplar ist eine ID für die Datenquelle mit der uid tempo.
  • Exemplars kommen nur im Format OpenMetrics mit. Prometheus fragt beim Scrape danach, und metrics.go liefert es (EnableOpenMetrics: true).

Prometheus startet dabei neu. Warte zwei Minuten, dann:

curl -s -G localhost:30090/api/v1/query_exemplars \
  --data-urlencode 'query=notes_http_request_duration_seconds_bucket{path="/notes"}' \
  | jq -c '[.data[].exemplars[]] | max_by(.timestamp)'

Erwartet (die Werte weichen ab):

{"labels":{"trace_id":"2ba42003570347f798601e62ce5fc5ec"},"value":"0.004729009","tim...

Ein Messwert von knapp 5 ms, und die Anfrage dazu hat einen Namen. [.data[].exemplars[]] sammelt die Exemplars aller Zeitreihen – eine pro Bucket, Methode und Pod –, max_by(.timestamp) nimmt das jüngste.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Vom Ausreißer zum Trace

Exemplars lohnen sich bei Ausreißern. Erzeuge welche:

kubectl -n app set env deploy/notes-api NOTES_DELAY=400ms
kubectl -n app rollout status deploy/notes-api

Erwartet (letzte Zeile):

deployment "notes-api" successfully rolled out

Nach einer Minute – Exemplars aus dem Bucket bis 0,5 s:

curl -s -G localhost:30090/api/v1/query_exemplars \
  --data-urlencode 'query=notes_http_request_duration_seconds_bucket{
      path="/notes",le="0.5"}' \
  | jq -r '[.data[].exemplars[]] | max_by(.timestamp) | .labels.trace_id'

Erwartet (die ID weicht ab):

5c95769a748799950184fc29350188eb

Mit dieser ID nach Tempo:

curl -s localhost:30320/api/v2/traces/5c95769a748799950184fc29350188eb \
  | jq -r '.trace.resourceSpans[].scopeSpans[].spans[]
           | [.name, ((.endTimeUnixNano|tonumber) - (.startTimeUnixNano|tonumber))/1e6]
           | @tsv'

Erwartet:

SELECT  8.296192
GET /notes  410.344192

Die Anfrage dauerte 410 ms, die Abfrage an Postgres 8 ms. Die Zeit ging also nicht in der Datenbank verloren, sondern in notes-api selbst – genau dort, wo faults.go wartet. Ohne Trace wüsstest du nur: „Es ist langsam.“

Störung zurücknehmen:

kubectl -n app set env deploy/notes-api NOTES_DELAY-

Fortschritt speichern? Kostenlos registrieren

Drill 4: Die Verbindungen in Grafana

Loki soll Trace-IDs in Logzeilen als Link zu Tempo zeigen, Tempo soll zu den Logs zurückführen. Beides sind Einstellungen der Datenquellen. Ersetze die beiden ConfigMaps aus Tag 7 und Tag 10:

cat > loki-datasource.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: loki-datasource
  namespace: monitoring
  labels:
    grafana_datasource: "1"
data:
  loki.yaml: |
    apiVersion: 1
    datasources:
      - name: Loki
        uid: loki
        type: loki
        url: http://loki.monitoring:3100
        jsonData:
          derivedFields:
            - name: trace_id
              matcherType: regex
              matcherRegex: '"trace_id":"(\w+)"'
              datasourceUid: tempo
              url: "$${__value.raw}"
EOF
cat > tempo-datasource.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata:
  name: tempo-datasource
  namespace: monitoring
  labels:
    grafana_datasource: "1"
data:
  tempo.yaml: |
    apiVersion: 1
    datasources:
      - name: Tempo
        uid: tempo
        type: tempo
        url: http://tempo.monitoring:3200
        jsonData:
          tracesToLogsV2:
            datasourceUid: loki
            filterByTraceID: true
            spanStartTimeShift: -5m
            spanEndTimeShift: 5m
            customQuery: true
            query: '{namespace="app"} |= "$${__trace.traceId}"'
EOF
kubectl apply -f loki-datasource.yaml -f tempo-datasource.yaml

Erwartet:

configmap/loki-datasource configured
configmap/tempo-datasource configured
  • derivedFields sucht mit einem regulären Ausdruck in jeder Logzeile. Was in der Klammer steht, wird zum Link auf die Datenquelle tempo.
  • tracesToLogsV2 fügt jedem Span einen Knopf hinzu, der in Loki nach der Trace-ID sucht, fünf Minuten vor und nach dem Span.
  • $${…}: Grafana ersetzt in Provisioning-Dateien ${…} durch Umgebungsvariablen. Das doppelte $ schützt die Platzhalter, die Grafana erst beim Klick füllen soll.

Hat Grafana die Änderung übernommen? Nach einer halben Minute:

curl -s -u admin:lab-grafana-pw-123 localhost:30300/api/datasources/uid/loki \
  | jq -c '.jsonData.derivedFields[0] | {name, datasourceUid, url}'

Erwartet:

{"name":"trace_id","datasourceUid":"tempo","url":"${__value.raw}"}

Probiere die Wege in der Oberfläche:

  1. Explore → Loki, Abfrage {app="notes-api"}. Klappe eine Zeile auf: Unter Fields steht trace_id mit einem Knopf zu Tempo. Ein Klick öffnet den Trace rechts daneben.

  2. Im Trace auf einen Span klicken, dann auf das Log-Symbol: Loki zeigt die Zeilen dieser Anfrage.

  3. Explore → Prometheus, Abfrage auf die Rohdaten – eine Recording Rule trägt keine Exemplars:

    histogram_quantile(0.95, sum by (le) (
      rate(notes_http_request_duration_seconds_bucket[5m])))

    Unter Options den Schalter Exemplars einschalten. Rauten über der Linie sind Exemplars; ein Klick zeigt die Trace-ID mit Link zu Tempo.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Eine Trace-ID aus einem Exemplar muss in allen drei Systemen auftauchen:

curl -s -G localhost:30090/api/v1/query_exemplars \
  --data-urlencode 'query=notes_http_request_duration_seconds_bucket{path="/notes"}' \
  | jq -r '[.data[].exemplars[]] | max_by(.timestamp) | .labels.trace_id'

Erwartet (die ID weicht ab):

2ba42003570347f798601e62ce5fc5ec

Setze die ID in beide folgenden Befehle ein:

curl -s localhost:30320/api/v2/traces/2ba42003570347f798601e62ce5fc5ec \
  | jq -r '.trace.resourceSpans[].scopeSpans[].spans[]
           | select(.kind == "SPAN_KIND_SERVER") | .name'
logcli query --quiet -o raw --since 15m \
  '{app="notes-api"} |= "2ba42003570347f798601e62ce5fc5ec"' | jq -r .msg

Erwartet (oder POST /notes – das Exemplar kann von beiden stammen):

GET /notes
request

Challenge

Löse mit NOTES_ERROR_RATE=0.2 Fehler aus. Beginne bei einer Logzeile mit level ERROR und finde heraus, ob der zugehörige Trace eine SQL-Abfrage enthält. Warum (nicht)?

Hinweis: logcli … | json | level="ERROR" liefert die Zeile, jq -r .trace_id die ID.

Lösung

kubectl -n app set env deploy/notes-api NOTES_ERROR_RATE=0.2
kubectl -n app rollout status deploy/notes-api
logcli query --quiet -o raw --limit 1 '{app="notes-api"} | json | level="ERROR"' \
  | jq -r .trace_id

Erwartet (die ID weicht ab):

141d4bbdbb40e3a23ae842eb4149ce05
curl -s localhost:30320/api/v2/traces/141d4bbdbb40e3a23ae842eb4149ce05 \
  | jq -r '.trace.resourceSpans[].scopeSpans[].spans[].name'

Erwartet:

GET /notes

Nur ein Span. handleNotes ruft f.inject() auf, bevor es die Datenbank fragt – die simulierte Störung entsteht in notes-api, nicht in Postgres. Der Trace beweist es: Es gab keine SQL-Abfrage. Zurücknehmen:

kubectl -n app set env deploy/notes-api NOTES_ERROR_RATE-

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Eine ID für alles: Die Trace-ID gehört auch in Fehlermeldungen an Nutzer und in Support-Tickets. Meldet jemand „Fehler 5b8aa5a2…“, ist die Anfrage in Sekunden gefunden.
  • Kontext über Grenzen: Message Queues, Batch-Jobs und Cron brechen die Kette, wenn niemand traceparent weiterreicht. Für Kafka, NATS und Co. gibt es Instrumentierungen, die die ID in Nachrichten-Header schreiben.
  • Metriken aus Traces: Tempo kann aus Spans selbst Metriken erzeugen (Metrics Generator): Raten, Fehler und Dauern pro Dienst und eine Karte, wer wen aufruft (Service Graph). Nützlich für Dienste, die selbst keine Metriken liefern.