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
traceparentweiter. 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:
otelhttperzeugt einen Span pro Anfrage,otelpgxeinen 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/readyErwartet (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: falseschaltet die anonyme Nutzungsstatistik an Grafana Labs ab.- Port 3200 ist die HTTP-API von Tempo.
tempo-externmacht 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 --waitErwartet (gekürzt):
Release "otel" has been upgraded. Happy Helming!
...
STATUS: deployed
otlp_grpc/tempospricht OTLP über gRPC mit dem Servicetempoauf Port 4317.tls.insecureverzichtet im Cluster auf TLS.debugbleibt 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
}
EOFotlptracehttp.Newbaut den Exporter. Ohne Optionen liest er die Adresse ausOTEL_EXPORTER_OTLP_ENDPOINT– eine Umgebungsvariable, die jedes OpenTelemetry-SDK in jeder Sprache versteht.resource.WithFromEnv()übernimmtOTEL_SERVICE_NAMEundOTEL_RESOURCE_ATTRIBUTES. Die Version kommt aus dem Code dazu.WithBatchersammelt Spans und schickt sie gebündelt im Hintergrund. Eine Anfrage wartet nie auf den Export.SetTracerProvidermacht den Provider global.otelhttpundotelpgxholen ihn sich von dort – darum musst du anmain.goundstore.gonichts ändern.TraceContextliest und schreibt den Headertraceparentnach 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 tidyErwartet (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/versionErwartet:
service/notes-api unchanged
deployment.apps/notes-api configured
...
deployment "notes-api" successfully rolled out
0.9.0
OTEL_EXPORTER_OTLP_ENDPOINTist die Basisadresse. Das SDK hängt/v1/tracesselbst an.OTEL_TRACES_SAMPLERfehlt 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 TracesErwartet (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.rootTraceNameist der Name des obersten Spans.main.gosetzt 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
otelhttpumfasst die ganze Anfrage, darunter der Client-Span vonotelpgxfür die Abfrage an Postgres. Er heißt nach dem SQL-Befehl, hierSELECT. - Die Reihenfolge der beiden Zeilen kann wechseln. Wer zu wem gehört,
steht in
parentSpanId. .scope.namezeigt, welche Bibliothek den Span erzeugt hat, etwagithub.com/exaring/otelpgx.split("/") | lastbehä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-apiErwartet (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.gowartet 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.yamlErwartet:
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/upstreamErwartet:
{"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_traceidratiomitOTEL_TRACES_SAMPLER_ARG=0.1behä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.textenthä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.