How-to: Dein lokaler Observability-Stack für Python mit OpenTelemetry, Grafana & Co.

Fehlermeldungen ohne Kontext? Plötzliche Performance-Einbrüche? Wenn du eine Python-Anwendung betreibst, kennst du diese Probleme. Oft fehlt die nötige Transparenz, um schnell zu verstehen, was im Inneren deiner App wirklich vor sich geht. Dieser Artikel zeigt dir, wie du dieses Problem löst.

Wir bauen gemeinsam einen kompletten, lokalen Observability-Stack für eine Python-Anwendung auf. Du lernst, wie du mit Werkzeugen wie OpenTelemetry, Grafana, Loki, Tempo, Prometheus und Alloy einen tiefen Einblick in deine App erhältst. Am Ende dieser Anleitung hast du eine voll funktionsfähige Umgebung auf deinem Rechner, die Logs, Traces und Metriken sammelt, speichert und visualisiert. So bist du für die nächste Fehlersuche perfekt gewappnet.

Teil dieses Blogposts ist ein Beispiel-Repository, das du als Sprungbrett nutzen kannst.

Die Basis: Was du brauchst und der Startschuss

Du benötigst lediglich zwei Dinge, die auf deinem System installiert sind.

• Docker
• Docker Compose

In 60 Sekunden startklar: Der komplette Stack mit Docker

Das gesamte Setup wird über Docker Compose verwaltet. Klone zunächst das Beispiel-Repository und starte alle Dienste mit einem einzigen Befehl im Hauptverzeichnis deines Projekts:

1docker-compose up -d

Dieser Befehl startet deine Python-Anwendung sowie alle notwendigen Observability-Tools. Das war's schon. Der Stack läuft.

Die Säulen der Observability

Und was macht der Stack nun? Telemetrie-Daten erstellen, sammeln, verwalten und sichtbar machen und Observability ermöglichen. Observability meint die Fähigkeit, den inneren Zustand eines komplexen Systems allein durch die Beobachtung seiner von außen sichtbaren Signale zu verstehen. Observability wird in der Regel durch das Sammeln und Analysieren von drei Hauptdatentypen – den "drei Säulen" – erreicht:

• Logs: Detaillierte, zeitgestempelte Aufzeichnungen von Ereignissen, die in der Anwendung stattgefunden haben. Sie beantworten die Frage: "Was ist passiert?". Sie sind ideal für die Detailanalyse von spezifischen Vorkommnissen.
• Traces: Traces zeigen die gesamte Reise einer einzelnen Anfrage durch alle Komponenten und Dienste deiner Systemlandschaft. Ein Trace besteht aus mehreren Schritten (Spans) und visualisiert den Anfragefluss sowie die Dauer jeder einzelnen Operation. Sie beantworten die Frage: "Wo ist das Problem aufgetreten?". Sie sind unverzichtbar, um Engpässe zu identifizieren und das Zusammenspiel von Services zu verstehen.
• Metrics (Metriken): Aggregierte, numerische Daten über einen bestimmten Zeitraum, wie z. B. CPU-Auslastung oder Anfragen pro Sekunde. Sie beantworten die Frage: "Wie ist der Gesamtzustand?". Sie eignen sich perfekt, um Trends zu erkennen und Alarme für Systemzustände zu definieren.

Das Gehirn des Stacks: Wie Alloy deine Daten lenkt

Mit Grafana Alloy kannst du eine Telemetrie-Daten-Pipeline erstellen und definieren, wie Daten gesammelt, prozessiert und wohin sie exportiert werden. Hier kannst du auch den Status des Collectors überprüfen und die rohen Logs oder Traces einsehen. In einer Konfigurationsdatei (config.alloy) legst du einen einfachen, aber mächtigen Lebenszyklus für deine Daten fest:

• Inputs: Woher kommen die Daten? (z.B. Logs von Docker oder Traces von deiner App)
• Processing: Wie sollen die Daten aufbereitet werden? (z.B. unwichtige Infos filtern oder nützliche Labels hinzufügen)
• Outputs: Wohin sollen die aufbereiteten Daten gesendet werden? (z.B. Logs an Loki, Traces an Tempo)

Schritt 1: Das Fundament – Logging mit Loki

Die einfachste Form der Telemetrie sind Logs. Sie sind die erste Anlaufstelle, um zu sehen, was eine Anwendung tut.

So sammelst du automatisch Logs von deiner App

Im ersten Schritt konfigurierst du Alloy so, dass es alle Log-Ausgaben deines Python-App-Containers sammelt. Alloy erkennt den Container automatisch, sammelt den Log-Stream und fügt das Label service_name hinzu. So weißt du immer, welcher Log-Eintrag zu welcher Anwendung gehört. Anschließend leitet Alloy die Logs zur Speicherung an Loki weiter.

Live-Debugging: Überprüfe deinen Datenfluss in Alloy

Um zu sehen, ob alles funktioniert, bietet Alloy eine praktische Weboberfläche:

1. Öffne http://localhost:12345 in deinem Browser.
2. Navigiere zum Component Explorer und wähle die Komponente discovery.docker.linux.
3. Im Debug Tab siehst du nun die rohen Log-Daten, die Alloy live vom Docker-Daemon empfängt.

Im Alloy Graph kannst du live verfolgen, wie die Telemetriedaten durch dein Observability System fließen. Hier wurde der /task Endpunkt 8x aufgerufen.

Deine Logs in Grafana visualisieren

Du hast nun sichergestellt, dass Logs generiert werden, erfolgreich eingesammelt werden und in Alloy ankommen. Nun kannst du überprüfen, dass die Logs von Alloy zu Grafana kommen, dem zentralen Dashboard-Tool.

1. Öffne http://localhost:3000.
2. Logge dich ein (Standard Log-In Daten: admin / admin).
3. Klicke links auf das Kompass-Symbol (Explore).
4. Wähle oben die Datenquelle Loki aus.
5. Klicke auf Log browser, wähle das Label service_name und den Wert python-app aus.
6. Klicke auf Run query.

Du siehst jetzt eine saubere, durchsuchbare Liste aller Logs deiner FastAPI-Anwendung wie beispielhaft folgende:

Schritt 2: Mehr Kontext – Aussagekräftiges Tracing mit OpenTelemetry

Logs sind gut, aber ihnen fehlt der Kontext einer gesamten Anfrage. Traces füllen diese Lücke. Sie zeigen den kompletten Weg einer Anfrage durch deine Anwendung.

Von Logs zu Traces: Deine App mit OpenTelemetry instrumentieren

Nun erweiterst du deine Anwendung um OpenTelemetry. Dies ist der De-facto-Standard zur Erzeugung von Telemetriedaten. Durch eine automatische Instrumentierung musst du den Anwendungscode kaum ändern, denn OpenTelemetry fängt Anfragen ab und erzeugt daraus Traces.

Die Konfiguration von Alloy muss angepasst werden: Statt die Logs von Docker einzusammeln, empfängt Alloy nun Logs und Traces direkt von OpenTelemetry über OTLP. OTLP steht für OpenTelemetry Protocol. Es ist ein einheitliches, herstellerunabhängiges Protokoll zur Erzeugung und Übertragung von Telemetriedaten. Die Traces werden an Tempo weitergeleitet, dein Speichersystem für Traces. Dank der Herstellerunabhängigkeit könntest du statt Tempo aber auch ein anderes Backend-Tool wie z.B. Jaeger verwenden. Da OTLP ein offener Standard ist, bist du nicht an einen bestimmten Anbieter gebunden. Solange dein Analyse-Tool OTLP versteht, kannst du deine Daten dorthin senden, ohne deine Anwendung neu instrumentieren zu müssen.

Der "Aha-Moment": So verbindest du Logs und Traces

OpenTelemetry versieht Logs und Traces automatisch mit derselben TraceID. Dadurch kannst du sie miteinander verbinden. In Grafana führt das zu einem mächtigen Feature. Stell dir vor, du siehst dir einen langsamen Trace in Tempo an. Du entdeckst eine bestimmte Operation (auch Span genannt), die ein Problem verursacht hat. Mit einem einzigen Klick auf ein Link-Symbol neben diesem Span springst du direkt zu den exakten Log-Einträgen in Loki, die während dieser Operation geschrieben wurden. Du erhältst den perfekten Mix aus Überblick (Trace) und Detail (Logs).

Schritt 3: Das Gesamtbild – Aggregierte Metriken mit Prometheus

Deine aktuelle Anwendung beinhaltet Logs (Details) und Traces (Kontext). Nun fehlt nur noch eine Säule der Observability: Metriken.

Die dritte Säule: Anwendungsmetriken mit Prometheus erfassen

Metriken sind aggregierte, numerische Werte über einen Zeitraum. Beispiele hierfür könnten "Anzahl der Anfragen pro Sekunde" oder "durchschnittliche Antwortzeit" sein. Du nutzt Prometheus, um diese Zeitreihen-Daten zu speichern. Der neue Datenfluss ist simpel:

1. Die Python-App erzeugt Metriken durch OpenTelemetry (z.B. ein Zähler für verarbeitete Aufgaben).
2. Alloy empfängt diese Metriken via OTLP.
3. Alloy leitet sie an Prometheus zur Speicherung weiter.

Vom Zähler zum Graphen: Deine Metriken in Grafana

Genau wie bei Loki und Tempo ist Grafana bereits so konfiguriert, dass es Prometheus als Datenquelle kennt. Du kannst im Explore-View nun die Prometheus-Datenquelle auswählen und deine Metriken abfragen, zum Beispiel den Zähler tasks_processed_total. Damit kannst du Graphen erstellen, die dir den Zustand deiner Anwendung über die Zeit visualisieren.

Zusammenfassung & Ausblick

Herzlichen Glückwunsch! Du hast erfolgreich einen voll funktionsfähigen, lokalen Observability-Stack für deine Python-Anwendung aufgesetzt. Du kannst nun:

• Logs in Loki durchsuchen
• Anfragen als Traces in Tempo verfolgen
• Logs und Traces für eine schnelle Fehleranalyse korrelieren
• Anwendungsmetriken mit Prometheus sammeln und in Grafana visualisieren

Dies ist eine solide Grundlage. Von hier aus kannst du eigene, spezifische Dashboards in Grafana bauen, Alarme für kritische Metriken einrichten oder weitere Anwendungen an deinen Observability-Stack anbinden. Du hast nun die Werkzeuge, um die Blackbox deiner Anwendung zu öffnen und datengestützte Entscheidungen zu treffen.

Übrigens: Das Beispiel-Repository ist schrittweise über drei Feature-Branches gewachsen, um die einzelnen Säulen der Observability nacheinander einzuführen. Damit kannst du nachvollziehen, wie die einzelnen Komponenten aufeinander aufbauen können oder wie du vorgehen kannst, wenn OpenTelemetry nicht verfügbar ist, dich aber trotzdem Logs interessieren:

• Logs (feat/api-loki-alloy-grafana): Zuerst wurde eine FastAPI-App implementiert, die Logs erzeugt. Diese Logs werden vom Docker-Daemon an Alloy weitergeleitet, welches sie zur Speicherung an Loki sendet. In Grafana können die Logs visualisiert werden.
• Traces (feat/api-loki-alloy-grafana-tempo-otel): Im zweiten Schritt wurde die Anwendung mit OpenTelemetry instrumentiert. Alloy sammelt nun Logs und die neu hinzugekommenen Traces über das OTLP-Protokoll und leitet die Traces an Tempo weiter.
• Metriken (feat/api-loki-alloy-grafana-tempo-otel-metrics): Abschließend wurde der Stack um Metriken erweitert. Die Anwendung generiert nun auch Metriken, die von Alloy gesammelt und in Prometheus gespeichert werden.