Modul 13: Testing-Frameworks & Observability
Den Task-Service absichern und durchleuchten: Tests mit Testify (assert, require, Suite) und generierte Mocks mit mockery, Integrationstests gegen echtes Postgres mit Testcontainers, strukturiertes Logging mit slog, zap & zerolog, Prometheus-Metriken samt /metrics-Endpoint und OpenTelemetry-Tracing über Service-Grenzen hinweg.
Testify & Mocks: assert, require, Suite & mockery
Lektion 61 von 100
Wenn aus if got != want Bohrercode wird
Der tasksrv aus Modul 10 wächst: Der Worker liest aus der Queue, benachrichtigt andere Dienste, und die Testdateien füllen sich mit derselben Dreizeiler-Sequenz — if err != nil { t.Fatalf(...) }, if got != want { t.Errorf(...) }, immer wieder. In Lektion 41 hast du table-driven Tests mit der Standardbibliothek geschrieben, in Lektion 43 Fakes von Hand. Beides bleibt gültig — aber ab einer gewissen Testmenge lohnt sich die Standard-Antwort des Go-Ökosystems: github.com/stretchr/testify.
Testify ist die am weitesten verbreitete Test-Bibliothek für Go — nicht, weil die Standardbibliothek etwas nicht könnte, sondern weil assert und require die Prüfungen lesbar machen und bei Misserfolg automatisch Diffs ausgeben. Dazu kommt mit mockery ein Codegenerator, der Interfaces aus Lektion 43 in fertige Mocks übersetzt — inklusive strikter Erwartungsprüfung, die handgeschriebene Fakes oft vermissen lassen.
assert dokumentiert, require schützt
assert.Equal(t, want, got) markiert den Test als fehlgeschlagen und läuft weiter — gut für mehrere unabhängige Prüfungen. require.Equal(t, want, got) ruft intern t.FailNow() auf und bricht sofort ab — Pflicht, wenn alles Weitere vom Ergebnis abhängt: Erst require.NoError(t, err), dann der Zugriff auf das Ergebnis. Genau diese Unterscheidung fehlt in vielen Suites, und sie entscheidet, ob ein Test eine klar lesbare Fehlermeldung liefert oder einen maskierten Nil-Panik.
Ein Test mit beiden Familien — kompakt, mit Diff statt Selbstbau:
// tasks/priority_test.go
package tasks
import (
"testing"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
func TestParsePriority(t *testing.T) {
got, err := ParsePriority("P1")
require.NoError(t, err) // ohne Fehler kein sinnvolles got — abbrechen
assert.Equal(t, Priority(1), got)
assert.NotEmpty(t, got.Label())
_, err = ParsePriority("egal")
assert.ErrorIs(t, err, ErrInvalidPriority) // unabhängige Prüfung: weiterlaufen
}
// Terminal: go test -run TestParsePriority -v
// → === RUN TestParsePriority
// → --- PASS: TestParsePriority (0.00s)
//
// Terminal (bei einem Fehler): go test -run TestParsePriority
// → Error Trace: priority_test.go:14
// → Error: Not equal: expected: 1, actual: 2
Fixtures ohne Copy-Paste: die Suite
Der Store-Test braucht vor jedem Test einen frischen Zustand. Mit testing allein schreibt man das Setup in jede Testfunktion (oder in TestMain, Lektion 42); mit der Testify-Suite wird es eine Methode. SetupTest läuft vor jedem Test der Suite neu, SetupSuite genau einmal für alle — und die Assertions stehen als Methoden auf s bereit: s.Equal, s.Require().NoError.
// tasks/store_suite_test.go
package tasks
import (
"testing"
"github.com/stretchr/testify/suite"
)
type StoreSuite struct {
suite.Suite
store *Store
}
// SetupTest läuft vor jedem einzelnen Test — jeder Start mit leerem Store.
func (s *StoreSuite) SetupTest() {
s.store = NewStore()
}
func (s *StoreSuite) TestAddAssignsIDs() {
t1 := s.store.Add("Deploy vorbereiten")
t2 := s.store.Add("Rollback testen")
s.Equal(1, t1.ID)
s.Equal(2, t2.ID)
}
func TestStoreSuite(t *testing.T) {
suite.Run(t, new(StoreSuite))
}
// Terminal: go test -v
// → === RUN TestStoreSuite
// → === RUN TestStoreSuite/TestAddAssignsIDs
// → --- PASS: TestStoreSuite (0.00s)
mockery: Mocks generieren statt pflegen
Der Worker benachrichtigt über ein Notifier-Interface (die Nahtstelle aus Lektion 43). Der handgeschriebene Fake funktioniert — aber wenn das Interface wächst, musst du ihn manuell synchron halten. mockery (v2, github.com/vektra/mockery/v2) liest das Interface und erzeugt einen vollständigen Mock mit Erwartungen, Aufrufzählung und AssertExpectations. Konfiguriert über eine .mockery.yaml im Repo-Root, dann genügt ein barer mockery-Aufruf.
// notify/notify.go — das Interface, das der Worker konsumiert
package notify
//go:generate mockery --name Notifier --output ./mocks
type Notifier interface {
Send(taskID int, msg string) error
}
// worker_test.go — der generierte Mock in Aktion
package worker
import (
"testing"
"github.com/team/tasksrv/notify/mocks"
)
func TestFinishNotifies(t *testing.T) {
n := mocks.NewMockNotifier(t)
n.On("Send", 42, "Deploy abgeschlossen").Return(nil).Once()
NewWorker(n).Finish(42)
n.AssertExpectations(t) // schlägt fehl, wenn Send nicht (genau einmal) lief
}
// Terminal: go test -run TestFinishNotifies -v
// → === RUN TestFinishNotifies
// → --- PASS: TestFinishNotifies (0.00s)
⚠ Häufiger Fehler:
assert.NoError(t, err)auf den Fehler zu setzen, von dem alles Weitere abhängt. Der Test läuft weiter, greift auf ein leeres Ergebnis zu und stirbt mitinvalid memory address or nil pointer dereference— die eigentliche Ursache (der falsche Parse-Fehler) ist in der Panic begraben, der Stacktrace zeigt auf die Nutzbau-Zeile, nicht auf das Problem. Faustregel:requirefür Vorbedingungen (Fehler, Setup, Länge),assertfür gleichrangige Folgeschlüssel. In Suites dasselbe mits.Require().
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Integrationstests mit Testcontainers
Lektion 62 von 100
Der Repo-Test, der Datenbankverhalten NICHT nachbaut
Der tasksrv speist seit Modul 10 einen echten Postgres — getestet wird das Repo bislang gegen … nichts. Unit-Tests mit einem Fake-Store beweisen Logik, aber nicht, dass das SQL stimmt: ob ON CONFLICT feuert, ob die Migration tatsächlich eine Spalte anlegt, ob der Index existiert. Genau hier schlägt die Stunde von github.com/testcontainers/testcontainers-go: Die Bibliothek startet für den Test einen echten Docker-Container — gleiches Image, gleiche Version wie in Produktion — und räumt ihn danach wieder weg.
Damit ändert sich die Antwort auf eine alte Streitfrage. SQLite als Postgres-Double fällt weg, die gemockte DB-Schicht auch: Der Test läuft gegen die echte Engine, nur eben ephemeral und auf einem zufällig freien Host-Port. Voraussetzung ist eine laufende Docker-Umgebung (Daemon lokal oder via DOCKER_HOST remote) — Testcontainers orchestriert, es virtualisiert nicht selbst.
Der Container ist die Umgebung
Ein Integrationstest mit Testcontainers startet dasselbe Artefakt wie Produktion — etwa postgres:17-alpine —, wartet auf Bereitschaft und liefert dir einen Connection-String. Das Test-Setup und die Produktionsumgebung können nicht mehr auseinanderlaufen, weil es nur noch eine Definition der Datenbank gibt: das Image. Der Preis ist Startzeit: ein paar Sekunden pro Container, deshalb teilt man sich einen für viele Tests.
Der erste Integrationstest — Container starten, migrieren, speichern, lesen. Das Postgres-Modul (github.com/testcontainers/testcontainers-go/modules/postgres) bringt ein sinnvolles Default-Waiting mit: Es wartet auf die »database system is ready«-Logzeile, bevor Run zurückkehrt:
// integration/repo_test.go
//go:build integration
package integration
import (
"context"
"errors"
"testing"
"github.com/golang-migrate/migrate/v2"
_ "github.com/golang-migrate/migrate/v2/database/postgres"
_ "github.com/golang-migrate/migrate/v2/source/file"
"github.com/testcontainers/testcontainers-go/modules/postgres"
"github.com/team/tasksrv/tasks"
)
func TestRepoAddAndGet(t *testing.T) {
ctx := context.Background()
pg, err := postgres.Run(ctx, "postgres:17-alpine",
postgres.WithDatabase("tasks"),
postgres.WithUsername("app"),
postgres.WithPassword("test"),
)
if err != nil {
t.Fatalf("Container-Start: %v", err)
}
t.Cleanup(func() { _ = pg.Terminate(ctx) }) // Entsorgung ist Pflicht, Lektion 42
m, err := migrate.New("file://../../migrations",
pg.ConnectionString(ctx, "sslmode=disable"))
if err != nil {
t.Fatalf("Migrate-Init: %v", err)
}
if err := m.Up(); err != nil && !errors.Is(err, migrate.ErrNoChange) {
t.Fatalf("Migration: %v", err)
}
repo := tasks.NewRepo(pg.ConnectionString(ctx, "sslmode=disable"))
id, err := repo.Add(ctx, "Migration einmal echt durchlaufen")
if err != nil {
t.Fatalf("Add: %v", err)
}
got, err := repo.Get(ctx, id)
if err != nil || got.Title != "Migration einmal echt durchlaufen" {
t.Fatalf("Get: %v / %+v", err, got)
}
}
// Terminal: go test -tags=integration -v
// → === RUN TestRepoAddAndGet
// → --- PASS: TestRepoAddAndGet (3.8s) — echter Postgres 17, im Container gestartet und weggeräumt
Der Build-Tag integration hält die schnellen Unit-Tests frei davon: go test ./... läuft ohne Docker, go test -tags=integration ./... in der Pipeline gegen die echte Engine.
Ein Container für die ganze Suite
Zwei Sekunden Startzeit pro Test sind vertretbar — bei 40 Repo-Tests sind es zwei Minuten nicht. Das etablierte Muster: ein gemeinsamer Container in TestMain, jeder Test bekommt seine Datenbank oder Tabelle. Damit zahlt man die Startzeit einmal pro Paket statt einmal pro Testfunktion:
// integration/main_test.go
//go:build integration
package integration
import (
"context"
"log"
"os"
"testing"
"github.com/testcontainers/testcontainers-go/modules/postgres"
)
var dsn string
func TestMain(m *testing.M) {
ctx := context.Background()
pg, err := postgres.Run(ctx, "postgres:17-alpine",
postgres.WithDatabase("tasks"),
postgres.WithUsername("app"),
postgres.WithPassword("test"),
)
if err != nil {
log.Fatalf("Container-Start: %v", err)
}
dsn = pg.ConnectionString(ctx, "sslmode=disable")
code := m.Run() // alle Tests, gemeinsamer Server
_ = pg.Terminate(ctx) // exakt einmal, auch nach Panic in einem Test
os.Exit(code)
}
// Terminal: go test -tags=integration ./integration/
// → ok github.com/team/tasksrv/integration 9.4s — 41 Tests, 1 Container, 1 Start
⚠ Häufiger Fehler: Den Container starten und das
Terminatevergessen — etwa, weilt.Cleanupweggelassen oder ein frühert.Fatalfvor der Registrierung liegt. Jedergo test-Lauf hinterlässt dann einen laufenden Postgres-Container; nach einem Tag CI sind es hunderte, der Docker-Host geht ihm Speicher und Ports aus, und die Pipeline scheitert an etwas, das wie ein Netzwerkproblem aussieht.Terminateunmittelbar nach erfolgreichemRunregistrieren (Cleanup bzw.TestMain), und den Fehler beim Stoppen mindestens loggen.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Structured Logging: slog, zap & zerolog
Lektion 63 von 100
Von Zeilen, die niemand auswerten kann
Der tasksrv läuft, aber der Nightly-Job kommt seit Dienstag nicht durch. Die Logs bestehen aus Zeilen wie »starting import«, »done«, »something failed« — mit log.Printf gesetzt, in Textdateien geparkt. Welche Queue? Welcher Task? Wie lange hat’s gedauert? Nichts davon steht in der Zeile, also sucht das Team von Hand. Strukturiertes Logging dreht den Ansatz um: Jede Zeile ist ein Datensatz mit Feldern — und damit filterbar, aggregierbar, alarmierbar.
In Go gibt es seit Version 1.21 log/slog in der Standardbibliothek — der Reference-Punkt, an dem sich die Drittanbieter messen lassen müssen. Die zwei bekanntesten: go.uber.org/zap (Uber, typsichere Felder, sehr schnell) und github.com/rs/zerolog (zero-allocation, kettenbasierte API). Alle drei schreiben JSON statt Prosa — die Voraussetzung dafür, dass Logs, Metriken und Traces als Architektur-Disziplin zusammenwirken können, statt drei getrennte Silos zu bilden.
Felder statt Formate
logger.Info("task created", "task_id", 42, "queue", "ingest") schreibt die Werte als eigenständige Schlüssel in die Zeile — nicht in einen zusammengesetzten Satz. Genau das macht den Unterschied: queue="ingest" lässt sich in der Log-Plattform filtern und zählen; »Task 42 für Queue ingest erstellt« ist nur noch Volltext. Wer Werte in die Nachricht formattiert, verliert sie als Daten — egal wie gut die Nachricht liest.
slog seit Go 1.21: Handler entscheiden über das Format, With hängt kontextuelle Felder an jeden Nachfahren:
// tasksrv/main.go
package main
import (
"context"
"log/slog"
"os"
"time"
)
func main() {
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
Level: slog.LevelInfo,
}))
slog.SetDefault(logger) // auch net/http-Interna loggen ab hier strukturiert
// Kontext für alles Weitere in diesem Programmzweig:
ingest := logger.With("queue", "ingest", "region", "eu-central")
ingest.Info("task created",
slog.Int("task_id", 42),
slog.Duration("enqueue_wait", 3*time.Millisecond),
)
ingest.Error("queue stuck", slog.Duration("since_last", 90*time.Second))
}
// → {"time":"2026-11-05T10:14:03Z","level":"INFO","msg":"task created","queue":"ingest","region":"eu-central","task_id":42,"enqueue_wait":"3ms"}
// → {"time":"2026-11-05T10:15:33Z","level":"ERROR","msg":"queue stuck","queue":"ingest","region":"eu-central","since_last":"1m30s"}
Ein Logger pro Request (mit logger.With("trace_id", ...) aus Lektion 65) macht jede Zeile einem Aufruf zuordenbar — das ist die Grundlage für Korrelation über Service-Grenzen.
zap und zerolog: wenn jeder Byte zählt
Warum überhaupt eine Drittanbieter-Bibliothek, wenn slog im Standard ist? Beide Anbieter sind älter als slog und profilieren sich im heiklen Bereich: heißer Pfad, Millionen Zeilen pro Minute. zerolog schreibt ohne Allokationen, zap mit typisierten Feldern, die Reflexion vermeiden — und beide lassen sich seit Go 1.21 auch als slog-Handler einbinden, sodass der restliche Code bei slog bleiben kann:
// worker/log.go — zerolog im heißen Worker-Pfad
package worker
import (
"os"
"time"
"github.com/rs/zerolog"
)
var log = zerolog.New(os.Stdout).With().Timestamp().Caller().Logger()
func Handle(taskID int, wait time.Duration) {
log.Info().
Int("task_id", taskID).
Str("queue", "ingest").
Dur("wait", wait).
Msg("task picked up")
}
// → {"level":"info","caller":"/worker/log.go:14","task_id":42,"queue":"ingest","wait":"3ms","time":"2026-11-05T10:14:06.120Z","message":"task picked up"}
// notifier/log.go — zap mit typisierten Feldern
logger, _ := zap.NewProduction()
defer logger.Sync()
logger.Info("notification sent",
zap.Int("task_id", 42),
zap.String("channel", "matrix"),
zap.Int64("bytes", 312),
)
// → {"level":"info","ts":1762331646.120,"caller":"notifier/log.go:9","msg":"notification sent","task_id":42,"channel":"matrix","bytes":312}
Die ehrliche Empfehlung für einen Dienst wie tasksrv: mit slog starten — Standardbibliothek, keine Abhängigkeit, gut genug. Erst wenn Profile aus Lektion 44 zeigen, dass das Logging im heißesten Pfad wirklich messbar kostet, gezielt zap oder zerolog dort einsetzen; über Handler bleibt die API im Rest des Codes slog.
⚠ Häufiger Fehler: Zugangsdaten und personenbezogene Daten als Log-Felder schreiben —
"api_key","password","Authorization","email"landen mitslogoderzerologgnadenlos in der Zeile — und strukturierte Zeilen werden im Gegensatz zu Prosa maschinell indexiert, verschickt und monatelang aufbewahrt. Einlogger.Info("login", "password", pw)ist ein credentials-Leak mit Suchindex. Feldinhalte an Vertrauensgrenzen validieren (Lektion 8) und sensible Werte nie loggen — höchstens gehasht oder gekürzt.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
Prometheus-Metriken: Instrumentierung & /metrics
Lektion 64 von 100
Das Dashboard, das Auskunft geben muss
Der Product-Owner fragt Freitagmorgen: »Wie viele Tasks kommen pro Minute rein, und wie schnell sind wir?« — und niemand kann es beantworten, ohne in Logs zu wühlen. Logs aus Lektion 63 sagen dir, warum ein konkreter Task scheiterte; für den Zustand des Systems im Aggregat braucht es Metriken: Zahlen, die der Dienst laufend selbst publiziert. Der De-facto-Standard dafür ist Prometheus — und github.com/prometheus/client_golang bringt alles mit, was ein Go-Dienst dafür braucht.
Das Modell ist bewusst klein: Ein Counter zählt nur hoch (Anzahl Tasks), eine Gauge hält einen aktuellen Wert (Länge der Queue), ein Histogram verteilt Beobachtungen in Buckets (Anfragedauer). Der Dienst exportiert diese Zeitreihen auf einem /metrics-Endpoint im Textformat; der Prometheus-Server scrapped ihn alle 15 Sekunden. Kein Agent, kein Sidecar — ein HTTP-Handler.
Labels sind Dimensionen, keine Daten
Ein Label wie queue="ingest" macht aus einem Counter eine Familie von Zeitreihen — eine pro Queue. Das ist die Stärke (»Zeig die Rate je Queue«) und die Falle: Jede neue Label-Ausprägung erzeugt eine neue Zeitreihe. Fünf Queues: fein. Fünfzigtausend User-IDs: Speicher- und Abfrage-Desaster (Kardinalitäts-Explosion). Faustregel: Labels nur für kleine, vorher bekannte Wertemengen; alles Identifizierende (Task-ID, User, Pfad-Parameter) gehört in Traces und Logs aus den Nachbar-Lektionen — als Disziplin eingeordnet im Observability-Modul des Architektur-Kurses.
Zwei Metriken für den tasksrv — Counter und Histogram, registriert per promauto beim Paket-Import:
// metrics/metrics.go
package metrics
import (
"github.com/prometheus/client_golang/prometheus"
"github.com/prometheus/client_golang/prometheus/promauto"
)
var (
TasksCreated = promauto.NewCounterVec(prometheus.CounterOpts{
Name: "tasksrv_tasks_created_total",
Help: "Aufgenommene Tasks insgesamt, nach Queue.",
}, []string{"queue"})
HandlerDuration = promauto.NewHistogramVec(prometheus.HistogramOpts{
Name: "tasksrv_handler_duration_seconds",
Help: "HTTP-Handler-Dauer in Sekunden.",
Buckets: []float64{0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1},
}, []string{"route", "method"})
)
// Terminal (direkt nach dem Start): curl -s localhost:8080/metrics | grep _count
// → tasksrv_handler_duration_seconds_count{method="POST",route="/tasks"} 0
Die Instrumentierung im Handler — zwei Zeilen im Code, ein komplettes RED-Dashboard in der Ops-Ansicht — plus der Endpoint selbst, der sich wie jeder andere Handler in den Mux aus Lektion 46 einhängt:
// main.go
mux := http.NewServeMux()
mux.HandleFunc("POST /tasks", func(w http.ResponseWriter, r *http.Request) {
start := time.Now()
// ... Validierung und Store-Logik aus Lektion 47 ...
metrics.TasksCreated.WithLabelValues("api").Inc()
metrics.HandlerDuration.WithLabelValues("/tasks", "POST").
Observe(time.Since(start).Seconds())
})
mux.Handle("GET /metrics", promhttp.Handler())
// Terminal: curl -s localhost:8080/metrics | grep tasksrv_tasks_created
// → # HELP tasksrv_tasks_created_total Aufgenommene Tasks insgesamt, nach Queue.
// → # TYPE tasksrv_tasks_created_total counter
// → tasksrv_tasks_created_total{queue="api"} 128
Warum ein Histogram und nicht einen Gauge mit dem Durchschnitt? Weil Durchschnitte Tail-Latenzen verstecken: Ein p95 von 800 ms bei einem Schnitt von 40 ms sieht in einer Average-Linie bequem gesund aus. Das Histogram hält die Verteilung in Buckets vor, Prometheus aggregiert daraus Quantile (histogram_quantile) — und das korrekt über Instanzen hinweg, weil Buckets addierbar sind, Durchschnitte von Durchschnitten aber nicht.
⚠ Häufiger Fehler: Unbeschränkte Werte als Labels — klassisch
pathinklusive Pfad-Parameter (/tasks/4291/…) oder gleichuser_id. Jede neue ID erzeugt eine neue Zeitreihe; nach einer Woche hat der/metrics-Output Millionen Serien, der Prometheus-Server rennt gegen Speicher- und Timeouts, und die Metriken des Dienstes sind unbrachbar. Labels auf feste Mengen begrenzen (route="/tasks"statt echtem Pfad) und Einzelheiten in Logs und Traces belassen.
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren:
OpenTelemetry Tracing über Service-Grenzen
Lektion 65 von 100
Der Fall, der über zwei Dienste führt
Ein Task verschwindet: Der Client hat ihn an den tasksrv geschickt, der Monitor zeigt ihn als »created« — aber die Benachrichtigung kommt nie an, und niemand weiß, wo die Kette riss. Logs der beiden Dienste nebeneinander zu legen, ist raten: Zeitstempel stimmen grob, aber welcher Log-Eintrag des Workers gehört zu genau diesem Request? Verteilte Systeme brauchen einen gemeinsamen Faden — und genau das ist Tracing. Ein Trace ist die eine ID, die alle Arbeitsschritte eines Requests über alle Dienste hinweg verbindet; die einzelnen Schritte heißen Spans.
go.opentelemetry.io/otel ist die vendor-neutrale Standard-Bibliothek dafür (CNCF, keine Bindung an einen Backend-Hersteller). Das Ablaufschema ist überall gleich: einen TracerProvider mit Exporter aufsetzen, Span-Informationen über den Kontext weiterreichen — context.Context aus Lektion 38 ist der Transportweg — und an Service-Grenzen per Propagation im HTTP-Header mitnehmen. Das Wire-Format dafür ist der W3C-Standard traceparent.
Der Trace-Kontext reist im Header
Ein Span entsteht nie im Nirgendwo: tracer.Start(ctx, ...) hängt ihn an den Span im Kontext — und nur im Kontext. Überschreitet der Aufruf eine Service-Grenze, injiziert der Client die aktuelle Trace-ID in den traceparent-Header, der Server extrahiert sie wieder. Erst dadurch werden zwei Spans in zwei Prozessen zu einem Baum. Das passiert nicht automatisch, weil net/http nichts von OpenTelemetry weiß — otelhttp.NewHandler übernimmt das Injizieren/Extrahieren für dich, ist aber selbst nur Middleware aus Lektion 48.
Schritt eins: Provider und Exporter. Für die Entwicklung reicht der Stdout-Exporter (go.opentelemetry.io/otel/exporters/stdout/stdouttrace) — Span für Span auf die Konsole; in Produktion zeigt derselbe Code auf einen OTLP-Collector:
// telemetry/tracer.go
package telemetry
import (
"context"
"go.opentelemetry.io/otel"
"go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
sdktrace "go.opentelemetry.io/otel/sdk/trace"
)
// InitTracer setzt den globalen Provider und gibt eine Shutdown-Funktion zurück.
func InitTracer(ctx context.Context) (func(context.Context) error, error) {
exp, err := stdouttrace.New(stdouttrace.WithPrettyPrint())
if err != nil {
return nil, err
}
tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exp))
otel.SetTracerProvider(tp)
return tp.Shutdown, nil // flusht beim Beenden noch ausstehende Spans
}
// main.go
shutdown, err := telemetry.InitTracer(ctx)
if err != nil {
log.Fatal(err)
}
defer shutdown(context.Background()) // ohne Shutdown gehen Batch-Spans verloren
// Terminal (beim Beenden): shutdown flusht die noch im Batch liegenden Spans
// → {"Name":"POST /api/tasks","TraceID":"4bf92f3577b34da6a3ce929d0e0e4736", ...} — genau jetzt, nicht beim Span-Ende
Schritt zwei: Span-Transport. Der Server umschließt seine Handler mit otelhttp — das erzeugt pro Request einen Span, extrahiert eingehende traceparent-Header und injiziert sie beim ausgehenden Call des Workers. Innere Spanes erzeugt der Code selbst, immer vom Kontext des Requests:
// tasksrv: Handler-Grenze und innerer Span
mux.Handle("/api/", otelhttp.NewHandler(apiMux, "api"))
func (s *Store) AddTask(ctx context.Context, title string) (Task, error) {
ctx, span := otel.Tracer("tasksrv/store").Start(ctx, "AddTask")
defer span.End()
span.SetAttributes(
attribute.String("task.title", title),
attribute.Int("task.queue_len", s.Len()),
)
task, err := s.insert(ctx, title)
if err != nil {
span.RecordError(err)
span.SetStatus(codes.Error, err.Error())
}
return task, err
}
// Terminal: curl -s -X POST localhost:8080/api/tasks — Trace-Debug auf beiden Diensten
// → {"Name":"POST /api/tasks","TraceID":"4bf92f3577b34da6a3ce929d0e0e4736","SpanID":"00f067aa0ba902b7", ...}
// → {"Name":"AddTask","TraceID":"4bf92f3577b34da6a3ce929d0e0e4736","ParentSpanID":"00f067aa0ba902b7", ...}
// → {"Name":"send notification","TraceID":"4bf92f3577b34da6a3ce929d0e0e4736", ...}
Gleiche TraceID, drei Spans, zwei Prozesse — das verschwundene Task-Problem von oben wird zu einer Frage von Sekunden: Trace-ID aus dem Request-Log (Lektion 63 hatte trace_id als Feld vorbereitet), ins Trace-Backend gesteckt, und man sieht die Lücke genau dort, wo der Worker nicht antwortet. Damit ist die Trias komplett: Metriken sagen ob, Logs sagen warum, Traces sagen wo — zusammengeführt im Observability-Modul des Architektur-Kurses. Damit steht das Fundament für Modul 14, in dem der Go-Dienst KI-Frameworks anbindet.
⚠ Häufiger Fehler: Innere Spans mit
context.Background()statt dem Request-Kontext starten —tracer.Start(context.Background(), "AddTask"). Der Span hat dann keine Eltern-Information, erzeugt einen eigenen, isolierten Trace, und in der Trace-Ansicht liegt er als verwaistes Einzelstück neben dem eigentlichen Request-Baum statt darin. Immer denctxweiterreichen, den der Handler hereingereicht hat (r.Context()bzw. den austracer.Startzurückgegebenen Kontext für die Kinder).
✅ Wichtige Erkenntnisse
Haken setzen, um deinen Lernfortschritt zu markieren: