Skip to content

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.

Fortschritt0/5 Lektionen
61

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 mit invalid 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: require für Vorbedingungen (Fehler, Setup, Länge), assert für gleichrangige Folgeschlüssel. In Suites dasselbe mit s.Require().

✅ Wichtige Erkenntnisse

Haken setzen, um deinen Lernfortschritt zu markieren:

    62

    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 Terminate vergessen — etwa, weil t.Cleanup weggelassen oder ein früher t.Fatalf vor der Registrierung liegt. Jeder go 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. Terminate unmittelbar nach erfolgreichem Run registrieren (Cleanup bzw. TestMain), und den Fehler beim Stoppen mindestens loggen.

    ✅ Wichtige Erkenntnisse

    Haken setzen, um deinen Lernfortschritt zu markieren:

      63

      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 mit slog oder zerolog gnadenlos in der Zeile — und strukturierte Zeilen werden im Gegensatz zu Prosa maschinell indexiert, verschickt und monatelang aufbewahrt. Ein logger.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:

        64

        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 path inklusive Pfad-Parameter (/tasks/4291/…) oder gleich user_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:

          65

          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 den ctx weiterreichen, den der Handler hereingereicht hat (r.Context() bzw. den aus tracer.Start zurückgegebenen Kontext für die Kinder).

          ✅ Wichtige Erkenntnisse

          Haken setzen, um deinen Lernfortschritt zu markieren:

            This site uses essential cookies for Stripe payments. No tracking cookies.