Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 10: Traces mit Tempo

Ziel: notes-api schickt Traces über den Collector an Tempo, und du findest mit TraceQL langsame und fehlerhafte Anfragen bis hinunter zur SQL-Abfrage. · Dauer: ca. 90 min · Voraussetzung: Tag 9

Briefing

  • Ein Trace ist der Weg einer Anfrage durch das System. Er besteht aus Spans: einer pro Arbeitsschritt, mit Start, Dauer, Name und Attributen. Spans hängen als Baum aneinander.
  • Alle Spans eines Traces teilen sich eine Trace-ID. Ruft ein Dienst einen anderen auf, reicht er sie im HTTP-Header traceparent weiter. Das heißt Propagation.
  • Tempo speichert Traces. Wie Loki indiziert es wenig und ist dadurch billig. Gesucht wird mit TraceQL, etwa { span.http.response.status_code = 500 }.
  • In notes-api ist schon alles vorbereitet: otelhttp erzeugt einen Span pro Anfrage, otelpgx einen pro SQL-Abfrage. Es fehlt nur der Teil, der die Spans verschickt.
 notes-api ── OTLP/HTTP :4318 ──► Collector ── OTLP/gRPC :4317 ──► Tempo ◄── curl :30320
   GET /notes                                                         ▲
     └─ SELECT                                                      Grafana

Drill 1: Tempo installieren

cd ~/obs-lab
cat > tempo.yaml <<'EOF'
tempo:
  reportingEnabled: false
  retention: 24h
  receivers:
    otlp:
      protocols:
        grpc:
          endpoint: 0.0.0.0:4317
        http:
          endpoint: 0.0.0.0:4318
  resources:
    requests: {cpu: 50m, memory: 128Mi}
    limits: {memory: 512Mi}

persistence:
  enabled: true
  size: 2Gi
EOF
helm install tempo oci://ghcr.io/grafana-community/helm-charts/tempo --version 3.2.1 \
  -n monitoring -f tempo.yaml --wait
cat > tempo-extern.yaml <<'EOF'
apiVersion: v1
kind: Service
metadata:
  name: tempo-extern
  namespace: monitoring
spec:
  type: NodePort
  selector:
    app.kubernetes.io/name: tempo
  ports:
    - port: 3200
      nodePort: 30320
EOF
kubectl apply -f tempo-extern.yaml
curl -s localhost:30320/ready

Erwartet (gekürzt):

Pulled: ghcr.io/grafana-community/helm-charts/tempo:3.2.1
...
STATUS: deployed
...
service/tempo-extern created
ready
  • Das Chart installiert Tempo als einen Prozess – wie Loki im Modus Monolithic.
  • receivers.otlp öffnet die OTLP-Ports. Tempo nimmt Traces direkt an, der Collector ist dafür nicht Pflicht – aber der bessere Weg.
  • retention: 24h: Traces sind groß. Einen Tag aufzubewahren reicht im Lab.
  • reportingEnabled: false schaltet die anonyme Nutzungsstatistik an Grafana Labs ab.
  • Port 3200 ist die HTTP-API von Tempo. tempo-extern macht sie wie bei Loki unter einem festen NodePort erreichbar.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Der Collector schickt an Tempo

Die Pipeline traces bekommt einen zweiten Exporter. Hier die ganze otel.yaml:

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_grpc/tempo:
      endpoint: tempo:4317
      tls:
        insecure: true
    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, otlp_grpc/tempo]
      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 upgrade otel open-telemetry/opentelemetry-collector --version 0.178.2 \
  -n monitoring -f otel.yaml --wait

Erwartet (gekürzt):

Release "otel" has been upgraded. Happy Helming!
...
STATUS: deployed
  • otlp_grpc/tempo spricht OTLP über gRPC mit dem Service tempo auf Port 4317. tls.insecure verzichtet im Cluster auf TLS.
  • debug bleibt in der Pipeline. So siehst du im Log des Collectors weiterhin, dass etwas ankommt.

Fortschritt speichern? Kostenlos registrieren

Drill 3: notes-api verschickt Spans

telemetry.go enthält bisher nur eine leere Funktion. Ersetze die Datei:

cd ~/obs-lab/code/notes-api
cat > telemetry.go <<'EOF'
package main

// setupTelemetry schickt Traces per OTLP an den Collector. Ziel, Dienstname und
// Sampling kommen aus den Standard-Variablen OTEL_EXPORTER_OTLP_ENDPOINT,
// OTEL_SERVICE_NAME und OTEL_TRACES_SAMPLER.

import (
    "context"

    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp"
    "go.opentelemetry.io/otel/propagation"
    "go.opentelemetry.io/otel/sdk/resource"
    sdktrace "go.opentelemetry.io/otel/sdk/trace"
    semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
)

func setupTelemetry(ctx context.Context) (func(context.Context) error, error) {
    exp, err := otlptracehttp.New(ctx)
    if err != nil {
        return nil, err
    }
    res, err := resource.New(ctx, resource.WithFromEnv(),
        resource.WithAttributes(semconv.ServiceVersion(version)))
    if err != nil {
        return nil, err
    }
    tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exp), sdktrace.WithResource(res))
    otel.SetTracerProvider(tp)
    otel.SetTextMapPropagator(propagation.TraceContext{})
    return tp.Shutdown, nil
}
EOF
  • otlptracehttp.New baut den Exporter. Ohne Optionen liest er die Adresse aus OTEL_EXPORTER_OTLP_ENDPOINT – eine Umgebungsvariable, die jedes OpenTelemetry-SDK in jeder Sprache versteht.
  • resource.WithFromEnv() übernimmt OTEL_SERVICE_NAME und OTEL_RESOURCE_ATTRIBUTES. Die Version kommt aus dem Code dazu.
  • WithBatcher sammelt Spans und schickt sie gebündelt im Hintergrund. Eine Anfrage wartet nie auf den Export.
  • SetTracerProvider macht den Provider global. otelhttp und otelpgx holen ihn sich von dort – darum musst du an main.go und store.go nichts ändern.
  • TraceContext liest und schreibt den Header traceparent nach dem W3C-Standard.

Die neuen Pakete müssen in go.mod. Go läuft wie beim Bauen in einem Container:

docker run --rm -v "$PWD":/src -w /src golang:1.27-alpine go mod tidy

Erwartet (gekürzt):

go: finding module for package go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlp...
go: downloading ...
go: found go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp in go.opent...

go mod tidy sucht zu jedem Import das passende Modul, lädt es und trägt es in go.mod ein, seine Prüfsumme in go.sum.

Dann bauen und an k3s übergeben, diesmal als Version 0.9.0:

docker build -q -t notes-api:0.9.0 --build-arg VERSION=0.9.0 .
docker save notes-api:0.9.0 | sudo k3s ctr images import -

Erwartet (gekürzt):

sha256:fbc82eb20deabc4275d0e949cd1b9e76d07e219d88c38817bbc11a01d8f98724
docker.io/library/notes api:0.9.0         saved
...
Importing  elapsed: 1.9 s  total:   0.0 B  (0.0 B/s)

Fortschritt speichern? Kostenlos registrieren

Drill 4: Ausrollen

Das Manifest bekommt die neue Version und drei Umgebungsvariablen. NOTES_LOG_FORMAT aus Tag 8 steht jetzt fest darin – hier die ganze Datei:

cd ~/obs-lab/code
cat > k8s/notes-api.yaml <<'EOF'
# notes-api – zwei Pods, Image aus dem lokalen Build, Traces an den Collector
apiVersion: v1
kind: Service
metadata:
  name: notes-api
  namespace: app
  labels:
    app.kubernetes.io/name: notes-api
spec:
  type: NodePort
  selector:
    app.kubernetes.io/name: notes-api
  ports:
    - name: http
      port: 8080
      nodePort: 30080
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: notes-api
  namespace: app
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: notes-api
  template:
    metadata:
      labels:
        app.kubernetes.io/name: notes-api
    spec:
      initContainers:
        - name: migrate
          image: notes-api:0.9.0
          args: [migrate]
          env:
            - name: NOTES_DB_URL
              valueFrom:
                secretKeyRef: {name: notes, key: db-url}
      containers:
        - name: notes-api
          image: notes-api:0.9.0
          env:
            - name: NOTES_API_KEY
              valueFrom:
                secretKeyRef: {name: notes, key: api-key}
            - name: NOTES_DB_URL
              valueFrom:
                secretKeyRef: {name: notes, key: db-url}
            - name: NOTES_LOG_FORMAT
              value: json
            - name: OTEL_SERVICE_NAME
              value: notes-api
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: http://otel-collector.monitoring:4318
          ports:
            - name: http
              containerPort: 8080
          readinessProbe:
            httpGet: {path: /healthz, port: http}
          resources:
            requests: {cpu: 50m, memory: 32Mi}
            limits: {memory: 128Mi}
EOF
kubectl apply -f k8s/notes-api.yaml
kubectl -n app rollout status deploy/notes-api
curl -s localhost:30080/version

Erwartet:

service/notes-api unchanged
deployment.apps/notes-api configured
...
deployment "notes-api" successfully rolled out
0.9.0
  • OTEL_EXPORTER_OTLP_ENDPOINT ist die Basisadresse. Das SDK hängt /v1/traces selbst an.
  • OTEL_TRACES_SAMPLER fehlt mit Absicht: Ohne die Variable zeichnet das SDK jeden Trace auf. Im Lab ist das richtig, im Betrieb selten (Enterprise-Notiz).

Kommt etwas an? Der Collector zählt mit:

kubectl -n monitoring logs deploy/otel-collector --since 1m | grep -c Traces

Erwartet (ungefähr):

23

Eine Zeile pro gebündelter Sendung: Das SDK in jedem der zwei Pods schickt etwa alle fünf Sekunden, was sich angesammelt hat.

Fortschritt speichern? Kostenlos registrieren

Drill 5: TraceQL

Die letzten drei Traces von notes-api:

curl -s -G localhost:30320/api/search --data-urlencode limit=3 \
  --data-urlencode 'q={ resource.service.name = "notes-api" }' \
  | jq -r '.traces[] | [.traceID, .rootTraceName, .durationMs] | @tsv'

Erwartet (IDs und Dauern weichen ab):

21d52f01faab33234edbe8f127b78d40    GET /notes  10
2c06e4b14663095b770ccb4802147d86    POST /notes 2
26f3f709241cccb4cb7cd57a68796b34    POST /notes 3
  • { … } wählt Spans aus. resource. greift auf Resource Attributes zu, span. auf Attribute des einzelnen Spans.
  • rootTraceName ist der Name des obersten Spans. main.go setzt ihn auf Methode und Pfad.

Einen Trace ansehen – setze eine ID aus deiner Ausgabe ein:

curl -s localhost:30320/api/v2/traces/21d52f01faab33234edbe8f127b78d40 \
  | jq -r '.trace.resourceSpans[].scopeSpans[] | (.scope.name | split("/") | last) as $s
           | .spans[] | [$s, .name, .kind] | @tsv'

Erwartet (die Reihenfolge kann wechseln):

otelhttp    GET /notes  SPAN_KIND_SERVER
otelpgx SELECT  SPAN_KIND_CLIENT
  • Zwei Spans: Der Server-Span von otelhttp umfasst die ganze Anfrage, darunter der Client-Span von otelpgx für die Abfrage an Postgres. Er heißt nach dem SQL-Befehl, hier SELECT.
  • Die Reihenfolge der beiden Zeilen kann wechseln. Wer zu wem gehört, steht in parentSpanId.
  • .scope.name zeigt, welche Bibliothek den Span erzeugt hat, etwa github.com/exaring/otelpgx. split("/") | last behält nur das letzte Stück.

Und was hat Postgres getan?

curl -s localhost:30320/api/v2/traces/21d52f01faab33234edbe8f127b78d40 \
  | jq -r '.. | .attributes? // empty | .[] | select(.key == "db.query.text")
           | .value.stringValue'

Erwartet:

SELECT id::text, text FROM notes ORDER BY created_at DESC, id LIMIT 100

Die SQL-Abfrage aus store.go, ohne eine Zeile Code für Traces in store.go.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Langsame und fehlerhafte Anfragen

Löse beide Störungen auf einmal aus:

kubectl -n app set env deploy/notes-api NOTES_DELAY=200ms NOTES_ERROR_RATE=0.1
kubectl -n app rollout status deploy/notes-api

Erwartet (letzte Zeile):

deployment "notes-api" successfully rolled out

Nach einer halben Minute: Welche Anfragen sind gescheitert?

curl -s -G localhost:30320/api/search --data-urlencode limit=3 \
  --data-urlencode 'q={ span.http.response.status_code >= 500 }' \
  | jq -r '.traces[] | [.rootTraceName, .durationMs] | @tsv'

Erwartet:

GET /notes  203
GET /notes  200

Vielleicht weniger als drei Treffer – in einer halben Minute scheitert nicht viel.

  • Gescheiterte Anfragen dauern auch 200 ms: faults.go wartet erst und scheitert dann.
  • Die Attribute heißen nach den Semantic Conventions von OpenTelemetry: http.response.status_code, http.request.method, url.path. Jede Bibliothek in jeder Sprache verwendet dieselben Namen.

Und alle, die länger als 150 ms gedauert haben, aber gelungen sind:

curl -s -G localhost:30320/api/search --data-urlencode limit=3 \
  --data-urlencode 'q={ duration > 150ms && span.http.response.status_code < 400 }' \
  | jq -r '.traces[] | [.rootTraceName, .durationMs] | @tsv'

Erwartet:

GET /notes  211
GET /notes  210
GET /notes  215

duration ist die Dauer des Spans. && verknüpft Bedingungen, die derselbe Span erfüllen muss.

Störungen zurücknehmen:

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

Fortschritt speichern? Kostenlos registrieren

Drill 7: Tempo in Grafana

cd ~/obs-lab
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
EOF
kubectl apply -f tempo-datasource.yaml

Erwartet:

configmap/tempo-datasource created

In der Oberfläche: Explore, Datenquelle Tempo, Abfragetyp TraceQL, Abfrage { resource.service.name = "notes-api" }, Run query. Klicke auf eine Trace-ID: Rechts öffnet sich der Baum der Spans als Zeitleiste – oben GET /notes, darunter eingerückt SELECT mit der SQL-Abfrage in den Attributen.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

curl -s localhost:30320/api/v2/search/tag/resource.service.name/values \
  | jq -r '.tagValues[].value'

Erwartet:

notes-api

Nur notes-api hat Traces an Tempo geschickt. Die Traces von telemetrygen aus Tag 9 kamen nur bis debug – Tempo gab es da noch nicht.

curl -s -u admin:lab-grafana-pw-123 localhost:30300/api/datasources | jq -r '.[].name'

Erwartet:

Alertmanager
Loki
Prometheus
Tempo

Challenge

/upstream ruft https://example.com auf. Finde einen Trace dieses Aufrufs und zeige, dass er zwei Spans hat: den Server-Span von notes-api und einen Client-Span für die Anfrage nach außen.

Hinweis: Zuerst curl -s localhost:30080/upstream. Der Name des obersten Spans ist GET /upstream. TraceQL kennt das intrinsische Feld name.

Lösung

curl -s localhost:30080/upstream

Erwartet:

{"status":200,"url":"https://example.com"}

Eine halbe Minute später – so lange dauert es, bis der Trace gebündelt verschickt und in Tempo durchsuchbar ist:

curl -s -G localhost:30320/api/search --data-urlencode limit=1 \
  --data-urlencode 'q={ name = "GET /upstream" }' | jq -r '.traces[0].traceID'

Erwartet (die ID weicht ab):

bb27e60c38c2185fb6deeebd2b99aa6b

Mit dieser ID:

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

Erwartet:

GET /upstream   SPAN_KIND_SERVER
HTTP GET    SPAN_KIND_CLIENT

Der Client-Span kommt von otelhttp.NewTransport in main.go. Er hat auch den Header traceparent an example.com geschickt. Wäre example.com instrumentiert, würden seine Spans im selben Trace landen.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Sampling: Jeden Trace zu speichern ist teuer. OTEL_TRACES_SAMPLER=parentbased_traceidratio mit OTEL_TRACES_SAMPLER_ARG=0.1 behält etwa jeden zehnten. Besser ist Tail Sampling im Collector: Er wartet, bis ein Trace fertig ist, und behält alle mit Fehler oder hoher Dauer – und nur einen Bruchteil der normalen.
  • SQL in Spans: db.query.text enthält die Abfrage. Mit Parametern statt eingesetzten Werten ($1) landen keine Daten im Trace. Prüfe das für jede Bibliothek.
  • Automatische Instrumentierung: Für Java, .NET, Python und Node gibt es Agenten, die ohne Codeänderung Spans erzeugen. Der OpenTelemetry Operator injiziert sie per Annotation in Pods. Für Go gibt es eine eBPF-Variante.