Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 9: Observability II – Logs und Traces

Ziel: Gateway-Logs landen in Loki, jede Anfrage erzeugt einen Trace in Tempo, und du springst in Grafana vom Log-Eintrag zum Trace und zurück. · Dauer: ca. 150 min · Voraussetzung: Tag 8

Briefing

  • Metriken sagen dir, dass etwas schiefläuft (Tag 8), Logs und Traces sagen dir, bei welcher Anfrage und wo.
  • Loki indiziert nur Labels (Namespace, Pod, App), der Log-Inhalt wird bei der Abfrage gefiltert – billig, aber Labels klein halten.
  • Promtail ist seit 2. März 2026 End-of-Life. Nachfolger ist Grafana Alloy (alloy convert --source-format=promtail migriert alte Configs).
  • Die trace_id im JSON-Log ist das Bindeglied zwischen Loki und Tempo.
 llm-gateway ──stdout(JSON)──► Alloy ──push──► Loki ◄──┐
     │                                                  │ Grafana
     └──OTLP/HTTP :4318──► OTel Collector ──OTLP──► Tempo ◄──┘
                           (Tail Sampling)    trace_id verbindet beide

Drill 1: Loki monolithisch installieren

Loki- und Tempo-Charts liegen seit 2026 im Repo grafana-community. Die Values ($OBS/helm/loki-values.yaml) setzen deploymentMode: Monolithic, Dateisystem-Storage, 72 h Retention und schalten Caches, Gateway und Canary ab:

mkdir -p ~/sre-lab/tag09 && cd ~/sre-lab/tag09
OBS=~/sre-lab/code/observability
helm repo add grafana-community https://grafana-community.github.io/helm-charts
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update grafana-community grafana
helm template loki grafana-community/loki --version 18.15.1 -n monitoring \
  -f $OBS/helm/loki-values.yaml | grep -E '^kind:|image:' | sort | uniq -c
helm upgrade --install loki grafana-community/loki --version 18.15.1 \
  -n monitoring -f $OBS/helm/loki-values.yaml --wait
kubectl -n monitoring get pods -l app.kubernetes.io/name=loki

Erwartet (helm template live geprüft, Pod-Liste kann je nach Version abweichen):

   1 kind: ClusterRole
   1 kind: ClusterRoleBinding
   2 kind: ConfigMap
   3 kind: Service
   2 kind: ServiceAccount
   1 kind: StatefulSet
   1           image: docker.io/grafana/loki:3.7.8
   1           image: docker.io/kiwigrid/k8s-sidecar:2.14.1
NAME     READY   STATUS    RESTARTS   AGE
loki-0   2/2     Running   0          75s

Ein StatefulSet, ein PVC – mehr braucht Loki für ein paar GB am Tag nicht. Simple Scalable ist deprecated, für große Mengen gibt es den Distributed-Modus mit Objektspeicher.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Logs mit Alloy einsammeln

sed -n '/content: |/,$p' $OBS/helm/alloy-values.yaml | sed -n '2,7p;29,38p'
yq '.alloy.configMap.content' $OBS/helm/alloy-values.yaml > config.alloy
docker run --rm -v $PWD:/c grafana/alloy:v1.20.1 validate /c/config.alloy \
  && echo "Alloy-Config gültig"
helm upgrade --install alloy grafana/alloy --version 1.13.1 -n monitoring \
  -f $OBS/helm/alloy-values.yaml --wait

Erwartet (Validierung live, Install gekürzt):

      discovery.kubernetes "pods" {
        role = "pod"
        namespaces {
          names = ["llm-system", "tenant-acme", "tenant-globex"]
        }
      }
      loki.source.kubernetes "pods" {
        targets    = discovery.relabel.pods.output
        forward_to = [loki.write.default.receiver]
      }

      loki.write "default" {
        endpoint {
          url = "http://loki.monitoring.svc:3100/loki/api/v1/push"
        }
      }
Alloy-Config gültig
Release "alloy" does not exist. Installing it now.

Warum loki.source.kubernetes als Deployment? Es liest Logs über die Kubernetes-API (pods/log) statt per hostPath – ein Pod reicht, keine privilegierten Mounts. Bei vielen Nodes nimmst du ein DaemonSet mit loki.source.file auf /var/log/pods. Labels: nur namespace, pod, container, app. Den Mandanten filterst du im Inhalt.

Tipp: Kein yq? Kopiere den Block unter content: | von Hand in config.alloy.

Fortschritt speichern? Kostenlos registrieren

Drill 3: LogQL auf die Gateway-Logs

kubectl -n monitoring port-forward svc/loki 3100:3100 >/dev/null 2>&1 &
lr() {  # Log-Zeilen der letzten 30 min
  curl -s -G localhost:3100/loki/api/v1/query_range --data-urlencode "query=$1" \
    --data-urlencode since=30m --data-urlencode limit=${2:-3} \
    | jq -r '.data.result[].values[][1]'
}
lq() {  # Metrik-Abfrage (instant)
  curl -s -G localhost:3100/loki/api/v1/query --data-urlencode "query=$1" \
    | jq -r '.data.result[]
      | "\(.metric|tostring) \(.value[1]|tonumber*1000|round/1000)"'
}
lr '{namespace="llm-system", app="llm-gateway"} | json | status >= 500' 1
lq 'sum by (tenant) (count_over_time({app="llm-gateway"} | json | msg="request" [30m]))'
lq 'sum by (tenant) (rate({app="llm-gateway"} | json | status >= 500 [30m]))'
lq 'quantile_over_time(0.95, {app="llm-gateway"} | json | msg="request"
    | unwrap duration_ms [30m]) by (tenant)'
lr '{app="llm-gateway"} | json | level="ERROR"
    | line_format "{{.time}} {{.err}} trace={{.trace_id}}"' 1

Erwartet (Abfragen live gegen Loki 3.7.8 mit Lab-Logs; Zahlen, Zeiten und Adressen weichen bei dir ab):

{"time":"2026-10-09T18:50:14.888424+02:00","level":"INFO","msg":"request",
"tenant":"acme","method":"POST","path":"/v1/chat/completions","status":502,
"duration_ms":0,"trace_id":"c0197f6a31b519cdd9ae1c6ae527144a"}
{"tenant":"acme"} 788
{"tenant":"globex"} 857
{"tenant":"acme"} 0.042
{"tenant":"acme"} 934.35
{"tenant":"globex"} 836.4
2026-10-09T18:50:14.888386+02:00 dial tcp 10.96.12.7:11434: connect: connection refused
trace=c0197f6a31b519cdd9ae1c6ae527144a

(Lange Zeilen hier umbrochen.) Fällt dir etwas auf? 401 und 429 tauchen in den Logs nicht auf – das Gateway loggt nur Anfragen, die bis zum Proxy kommen. Für Abweisungen sind die Metriken aus Tag 8 die Quelle.

  • {app="llm-gateway"}: Stream-Selektor, nutzt den Index – steht immer vorn.
  • |= "text": Volltextfilter, billig – vor | json setzen.
  • | json: JSON-Felder werden zur Abfragezeit zu Labels (nicht gespeichert).
  • | unwrap duration_ms: Feld als Zahl für quantile_over_time & Co.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Das Gateway instrumentieren

Die fertige Version liegt in ~/sre-lab/code/llm-gateway-otel. Die Änderungen in fünf Schritten:

cd ~/sre-lab/code/llm-gateway-otel
go get go.opentelemetry.io/[email protected] go.opentelemetry.io/otel/[email protected] \
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/[email protected] \
  go.opentelemetry.io/contrib/instrumentation/net/http/[email protected]
  1. Tracer-Provider nur einschalten, wenn ein Endpunkt gesetzt ist. Endpunkt, Sampler und OTEL_SERVICE_NAME liest das SDK selbst aus der Umgebung:
func setupTracing(ctx context.Context) (func(context.Context) error, error) {
    otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(
        propagation.TraceContext{}, propagation.Baggage{}))
    if os.Getenv("OTEL_EXPORTER_OTLP_ENDPOINT") == "" {
        return func(context.Context) error { return nil }, nil // Tracing aus
    }
    exp, err := otlptracehttp.New(ctx)
    if err != nil {
        return nil, err
    }
    res, err := resource.New(ctx,
        resource.WithAttributes(attribute.String("service.name", "llm-gateway")),
        resource.WithFromEnv(), // OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES
        resource.WithTelemetrySDK())
    if err != nil {
        return nil, err
    }
    tp := sdktrace.NewTracerProvider(
        sdktrace.WithBatcher(exp), sdktrace.WithResource(res))
    otel.SetTracerProvider(tp)
    return tp.Shutdown, nil
}
  1. Server-Span für /v1/* (Probes und Scrapes ohne Spans), Client-Span plus traceparent-Header zum Modellserver:
    return otelhttp.NewHandler(mux, "llm-gateway",
        otelhttp.WithFilter(func(r *http.Request) bool {
            return strings.HasPrefix(r.URL.Path, "/v1/") // keine Spans für Probes
        }),
        otelhttp.WithSpanNameFormatter(func(_ string, r *http.Request) string {
            return r.Method + " " + r.URL.Path
        }))
        // in newProxy: Client-Span pro Upstream-Aufruf
        Transport:      otelhttp.NewTransport(http.DefaultTransport),
  1. Mandant und Tokens an den Server-Span, trace_id in jede Log-Zeile:
        span := trace.SpanFromContext(r.Context()) // Server-Span von otelhttp
        span.SetAttributes(attribute.String("tenant", tenant))
        // ...
        slog.Info("request", "tenant", tenant, "method", r.Method, "path", r.URL.Path,
            "status", rec.code, "duration_ms", d.Milliseconds(),
            "trace_id", traceID(r.Context()))
        // in countTokens: an den Server-Span, der Client-Span ist hier schon beendet
        if srv, ok := resp.Request.Context().Value(spanKey{}).(trace.Span); ok {
            srv.SetAttributes(
                attribute.Int("gen_ai.usage.input_tokens", u.Usage.Prompt),
                attribute.Int("gen_ai.usage.output_tokens", u.Usage.Completion))
        }
  1. In main() nach loadConfig() setupTracing aufrufen und nach srv.Shutdown shutdownTracing(shutdownCtx) – sonst gehen die letzten Spans beim Rollout verloren.

  2. Test mit In-Memory-Recorder (tracetest.NewSpanRecorder) und bauen:

go vet ./... && go test -count=1 -run TestTracing -v . 2>&1 | grep -v '^{' | tail -3
docker build -t llm-gateway:otel .
kind load docker-image llm-gateway:otel --name sre-lab

Erwartet (Test live, Build gekürzt):

--- PASS: TestTracing (0.00s)
PASS
ok      example.com/llm-gateway 0.219s
Image: "llm-gateway:otel" with ID "sha256:3b1f…" not yet present on node
"sre-lab-worker", loading...

Warum landen die Token-Attribute nicht am Client-Span? otelhttp beendet ihn, sobald der Response-Body gelesen und geschlossen ist – genau das macht countTokens. Attribute auf beendeten Spans verwirft das SDK stillschweigend. Der Test prüft deshalb gen_ai.usage.output_tokens.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Tempo und OpenTelemetry Collector

sed -n '/^processors:/,/^exporters:/p' $OBS/otel/collector.yaml
docker run --rm -v $OBS/otel:/c otel/opentelemetry-collector-contrib:0.161.0 \
  validate --config=/c/collector.yaml && echo "Collector-Config gültig"
helm repo add open-telemetry \
  https://open-telemetry.github.io/opentelemetry-helm-charts
helm upgrade --install tempo grafana-community/tempo --version 3.1.0 \
  -n monitoring -f $OBS/helm/tempo-values.yaml --wait
helm upgrade --install otelcol open-telemetry/opentelemetry-collector \
  --version 0.175.1 -n monitoring -f $OBS/helm/otel-collector-values.yaml --wait

Erwartet (Validierung live, Rest gekürzt):

processors:
  memory_limiter:
    check_interval: 5s
    limit_percentage: 80
    spike_limit_percentage: 25
  tail_sampling:
    decision_wait: 10s          # so lange auf alle Spans eines Traces warten
    num_traces: 20000
    policies:
      - name: fehler-immer
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: langsam-immer
        type: latency
        latency: { threshold_ms: 10000 }
      - name: rest-10-prozent
        type: probabilistic
        probabilistic: { sampling_percentage: 10 }
  batch: {}
exporters:
Collector-Config gültig

Der Exporter heißt seit Collector v0.144 otlp_grpc (vorher otlp), das Chart schreibt alte Namen automatisch um. Jetzt das Gateway umstellen:

kubectl -n llm-system set image deploy/llm-gateway '*=llm-gateway:otel'
kubectl -n llm-system set env deploy/llm-gateway \
  OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector.monitoring.svc:4318 \
  OTEL_RESOURCE_ATTRIBUTES=deployment.environment=lab
kubectl -n llm-system rollout status deploy/llm-gateway

Bei Default-Deny-Egress in llm-system braucht das Gateway zusätzlich eine Egress-Regel zu monitoring auf TCP 4318.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Traces finden mit TraceQL

kubectl -n llm-system port-forward svc/llm-gateway 8080:8080 >/dev/null 2>&1 &
kubectl -n monitoring port-forward svc/tempo 3200:3200 >/dev/null 2>&1 &
LLMCTL_API_KEY=lab-key-acme llmctl load -n 40 -c 2 >/dev/null
sleep 20   # decision_wait + Batch
tq() {
  curl -s -G localhost:3200/api/search --data-urlencode "q=$1" \
    | jq -r '.traces[]? | "\(.traceID) \(.rootTraceName) \(.durationMs)ms"'
}
tq '{resource.service.name="llm-gateway" && span.tenant="acme" && duration > 500ms}'
T=$(tq '{span.gen_ai.usage.output_tokens > 0}' | head -1 | cut -d' ' -f1)
curl -s localhost:3200/api/v2/traces/$T | jq -r '.trace.resourceSpans[].scopeSpans[]
  .spans[] | "\(.kind) \(.name) " + ([.attributes[]
  | select(.key|test("tenant|gen_ai|status_code"))
  | "\(.key)=\(.value|to_entries[0].value)"] | join(" "))'

Erwartet (live gegen Tempo 3.1.0, gekürzt; IDs und Zeiten weichen ab):

c343fb85dd022f8028c4711e3f68ec05 POST /v1/chat/completions 751ms
a71e628076a0cd2ec9d671469ff0c1fd POST /v1/chat/completions 602ms
SPAN_KIND_CLIENT HTTP POST http.response.status_code=200
SPAN_KIND_SERVER POST /v1/chat/completions tenant=acme gen_ai.usage.input_tokens=39
gen_ai.usage.output_tokens=30 http.response.status_code=200

Zwei Spans pro Anfrage: Server (Gateway) und Client (Aufruf zum Modellserver). Die Differenz ist Gateway-Overhead. vLLM kann selbst Spans erzeugen (--otlp-traces-endpoint) und hängt sich über den traceparent-Header an denselben Trace.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Logs und Traces in Grafana verbinden

sed -n '4,15p;21,27p' $OBS/helm/grafana-datasources.yaml
helm upgrade kps prometheus-community/kube-prometheus-stack --version 92.2.0 \
  -n monitoring -f $OBS/helm/kps-values.yaml \
  -f $OBS/helm/grafana-datasources.yaml --wait
curl -s -u admin:lab-admin localhost:3000/api/datasources \
  | jq -r '.[] | "\(.uid) \(.type)"'

Erwartet (Datei live, API gekürzt, kann je nach Version abweichen):

    - name: Loki
      type: loki
      uid: loki
      url: http://loki.monitoring.svc:3100
      access: proxy
      jsonData:
        derivedFields:                    # Log -> Trace
          - name: TraceID
            matcherRegex: '"trace_id":"(\w+)"'
            datasourceUid: tempo
            url: "$${__value.raw}"        # $$ = wörtliches $ im Provisioning
            urlDisplayLabel: Trace öffnen
      jsonData:
        tracesToLogsV2:                   # Trace -> Logs
          datasourceUid: loki
          spanStartTimeShift: "-5m"
          spanEndTimeShift: "5m"
          customQuery: true
          query: '{namespace="llm-system"} |= "$${__trace.traceId}"'
prometheus prometheus
alertmanager alertmanager
loki loki
tempo tempo

In Grafana unter Explore: Loki wählen, {app="llm-gateway"} | json | status >= 500 abfragen, Log-Zeile aufklappen, „Trace öffnen”. Im Trace-Panel führt das Log-Symbol am Span zurück zu allen Zeilen mit dieser trace_id.

Warum $$? Grafana ersetzt $VAR im Provisioning durch Umgebungsvariablen. $$ erzeugt ein wörtliches $, das Grafana erst zur Abfragezeit füllt.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Sampling-Strategie prüfen

for i in $(seq 60); do
  curl -s -o /dev/null -H 'Authorization: Bearer lab-key-globex' \
    localhost:8080/v1/models
done
kubectl -n llm-system scale deploy/ollama --replicas=0   # Variante A, Tag 7
LLMCTL_API_KEY=lab-key-acme llmctl load -n 5 -c 1 >/dev/null
kubectl -n llm-system scale deploy/ollama --replicas=1
sleep 20
tq '{resource.service.name="llm-gateway" && status=error}' | wc -l
tq '{name="GET /v1/models" && status!=error}' | wc -l

Erwartet (live, Zufallsanteil schwankt):

       5
       4

Alle 5 Fehler-Traces bleiben, von 60 erfolgreichen nur ein paar (Ziel 10 %). Das ist Tail Sampling: Der Collector entscheidet, nachdem der Trace komplett ist. Head Sampling (OTEL_TRACES_SAMPLER=parentbased_traceidratio, OTEL_TRACES_SAMPLER_ARG=0.1) entscheidet beim Start und verliert dabei Fehler.

Strategie Gut für Preis
Head (SDK) sehr viel Traffic, billig Fehler und Ausreißer gehen verloren
Tail (Collector) Fehler + langsame Anfragen immer behalten Puffer im RAM, alle Spans eines Traces auf denselben Collector
100 % Lab, wenig Traffic Speicher in Tempo

Sicherheit: Prompts und Antworten nie als Span-Attribut oder Log-Feld – sie enthalten Kundendaten. Token-Zahlen ja, Inhalte nein.

SigNoz ist die All-in-One-Alternative: ein Helm-Chart, OTLP direkt, Speicher in ClickHouse, Metriken, Logs und Traces in einer UI. Gut, wenn ein Kunde keinen Grafana-Stack betreiben will. Die Instrumentierung bleibt gleich – das ist der Vorteil von OpenTelemetry.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "Loki bereit" "curl -sf localhost:3100/ready"
check "Gateway-Logs in Loki" \
  "curl -s -G localhost:3100/loki/api/v1/query_range \
   --data-urlencode 'query={app=\"llm-gateway\"}' --data-urlencode since=1h \
   | jq -e '.data.result | length > 0'"
check "Tempo bereit" "curl -sf localhost:3200/ready"
check "Gateway-Traces in Tempo" \
  "curl -s -G localhost:3200/api/search \
   --data-urlencode 'q={resource.service.name=\"llm-gateway\"}' \
   | jq -e '.traces | length > 0'"
check "trace_id im Log" \
  "kubectl -n llm-system logs deploy/llm-gateway --tail=20 \
   | grep -q '\"trace_id\":\"[0-9a-f]\{32\}\"'"
check "Datenquelle tempo" \
  "curl -sf -u admin:lab-admin localhost:3000/api/datasources/uid/tempo"

Challenge

Ergänze eine Sampling-Policy, die alle Traces des Mandanten acme behält (Premium-Kunde mit Debug-Vertrag), und validiere die Config.

Hinweis: Die Policy string_attribute prüft Span-Attribute, das Gateway setzt tenant.

Lösung

cp $OBS/otel/collector.yaml ~/sre-lab/tag09/collector.yaml
python3 - <<'EOF'
import pathlib
p = pathlib.Path.home() / "sre-lab/tag09/collector.yaml"
s = p.read_text().replace("      - name: rest-10-prozent", """\
      - name: acme-immer
        type: string_attribute
        string_attribute: { key: tenant, values: [acme] }
      - name: rest-10-prozent""")
p.write_text(s)
EOF
docker run --rm -v ~/sre-lab/tag09:/c otel/opentelemetry-collector-contrib:0.161.0 \
  validate --config=/c/collector.yaml && echo "gültig"

Fortschritt speichern? Kostenlos registrieren

Interview-Notiz

  • Typische Frage: „Ein Kunde meldet sporadisch langsame Antworten. Wie gehst du vor?” – p95 je Mandant (Metrik) → langsame Traces per TraceQL → Span-Vergleich Gateway vs. Modellserver → Logs derselben trace_id.
  • Knackig: „Metriken für das Ob, Traces für das Wo, Logs für das Warum – verbunden über die Trace-ID.”
  • Sampling begründen können: Tail Sampling behält Fehler und Ausreißer, kostet aber RAM und braucht trace-ID-basiertes Load Balancing vor mehreren Collectors.
  • Brücke aus deiner Praxis: Vault/OpenBao-Audit-Logs hast du mit Request-IDs korreliert und HMAC-maskiert – dieselbe Disziplin gilt hier für Prompts: keine Inhalte in Logs oder Spans.
  • Vendor-Neutralität: Mit OpenTelemetry kann ein Kunde Tempo, SigNoz, Datadog oder Dynatrace nutzen, ohne dass du den Code änderst.

Enterprise-Notiz

  • Loki und Tempo produktiv mit Objektspeicher (S3, MinIO, Ceph) und im Distributed-Modus; Retention pro Mandant über limits_config/Overrides.
  • Multi-Tenancy in Loki/Tempo (X-Scope-OrgID), wenn Kunden eigene Log-Sichten bekommen.
  • Mehrere Collector-Replikas: vorne loadbalancing-Exporter nach Trace-ID, dahinter die Tail-Sampling-Stufe.
  • DSGVO: Prompts und Antworten bleiben aus Logs, Spans und Labels; Log-Retention mit dem Datenschutz abstimmen.
  • On-prem ohne Internet: Images, Charts und Grafana-Plugins spiegeln (Tag 14). Alloy kann Collector, Log-Shipper und Prometheus-Agent in einem Binary ersetzen.