FastAPI mit OpenTelemetry instrumentieren – in 15 Minuten

FastAPI mit OpenTelemetry instrumentieren

In vielen Python‑Microservices fehlt heute noch eine einheitliche Observability‑Strategie. FastAPI mit OpenTelemetry instrumentieren ermöglicht es, in nur 15 Minuten verteiltes Tracing aufzubauen und sofort messbare Verbesserungen bei MTTR und SLA‑Einhalten zu erzielen. Dieser Leitfaden führt Sie Schritt für Schritt durch ein vollständiges Projekt – von der Grundkonfiguration bis zur Produktion.

1. Projekt‑Setup und Grundgerüst

1.1. Initialisierung des Python‑Environments

python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn opentelemetry-sdk opentelemetry-instrumentation-fastapi opentelemetry-exporter-otlp

1.2. Minimaler FastAPI‑Code

from fastapi import FastAPI
app = FastAPI()

@app.get("/ping")
async def ping():
    return {"status": "ok"}

1.3. Erste Ausführung

uvicorn main:app --reload

Der Service läuft jetzt lokal, aber ohne Observability‑Daten.

2. OpenTelemetry‑Instrumentation einbinden

2.1. Was ist OpenTelemetry?

OpenTelemetry ist ein Open‑Source‑Framework, das standardisierte APIs für Tracing, Metrics und Logs bereitstellt. Es ermöglicht die einheitliche Erfassung von Telemetriedaten über verschiedene Programmiersprachen und Laufzeitumgebungen hinweg.

2.2. Warum FastAPI?

FastAPI nutzt das ASGI‑Interface, das sich ideal für asynchrone Middleware‑Einbindung eignet. Durch die native Unterstützung von OpenTelemetry‑Instrumentation können Spans automatisch erstellt werden, sobald ein Request eintrifft.

2.3. Konfiguration des Tracers

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

resource = Resource.create({"service.name": "fastapi-demo"})
provider = TracerProvider(resource=resource)
trace.set_tracer_provider(provider)

otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317", insecure=True)
span_processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(span_processor)

Damit wird jeder erzeugte Span an einen OTLP‑Collector gesendet – zum Beispiel den Lescopr‑Collector.

3. Middleware‑Einbindung und Kontext‑Propagation

3.1. Wie instrumentiere ich FastAPI mit OpenTelemetry?

Durch das Hinzufügen der OpenTelemetryMiddleware wird jeder eingehende HTTP‑Request automatisch mit einem Trace‑ und Span‑Kontext versehen. Die Middleware übernimmt das Parsen und Weiterleiten von traceparent‑Headern, sodass nachgelagerte Services den Kontext erhalten.

from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor

FastAPIInstrumentor().instrument_app(app)

3.2. Fehler‑Tracking aktivieren

from opentelemetry.instrumentation.logging import LoggingInstrumentor
LoggingInstrumentor().instrument(set_logging_format=True)

3.3. Liste der wichtigsten Middleware‑Komponenten

• OpenTelemetryMiddleware – automatisches Tracing von HTTP‑Requests
• LoggingInstrumentor – verbindet Python‑Logging mit Trace‑IDs
• CustomExceptionHandler – fügt Fehlermeldungen als Span‑Events hinzu

4. Exporter‑Konfiguration für Lescopr

4.1. OTLP‑Collector‑Setup

Lescopr stellt einen vollständig verwalteten OTLP‑Collector bereit. Die Verbindung erfolgt über gRPC auf Port 4317. Stellen Sie sicher, dass Netzwerk‑ und Firewall‑Regeln den Traffic zulassen.

4.2. Authentifizierung und DSGVO‑Konformität

Lescopr unterstützt Token‑basiertes Auth‑Header‑Signing. Ergänzen Sie den Exporter‑Aufruf wie folgt:

otlp_exporter = OTLPSpanExporter(
    endpoint="https://api.lescopr.com/otlp",
    headers=("authorization", "Bearer <YOUR_TOKEN>")
)

Damit werden alle Traces verschlüsselt übertragen und bleiben DSGVO‑konform.

5. Verifikation und erste Messwerte

5.1. Lokaler Collector‑Test

Starten Sie den Lescopr‑Collector im Docker‑Modus:

docker run -p 4317:4317 lescopr/collector:latest

Rufen Sie anschließend den Endpunkt /ping mehrmals auf und prüfen Sie das Lescopr‑Dashboard. Sie sollten einheitliche Spans mit korrekten trace_id‑Werten sehen.

5.2. Metriken für MTTR und SLA

Lescopr visualisiert automatisch:

• Durchschnittliche Latenz pro Endpoint
• Fehlerquote (5xx‑Responses)
• End‑to‑End‑Trace‑Zeit über mehrere Services hinweg

Durch das Hinzufügen von Custom Attributes (z. B. user_id, transaction_id) können Sie noch gezieltere Analysen durchführen.

6. Produktion und kontinuierliche Verbesserung

6.1. CI/CD‑Integration

Fügen Sie das Installations‑ und Test‑Skript in Ihre Pipeline ein, um sicherzustellen, dass jede neue Version korrekt instrumentiert ist.

steps:
  - name: Install dependencies
    run: pip install -r requirements.txt
  - name: Run integration tests
    run: pytest tests/

6.2. Monitoring‑Alarme

Lescopr ermöglicht das Setzen von SLA‑Alarme basierend auf Trace‑Statistiken. Beispiel: Alarm auslösen, wenn die 95‑Perzentil‑Latenz eines kritischen Endpoints > 250 ms beträgt.

6.3. Skalierung und Kostenkontrolle

Durch das gezielte Sampling (z. B. 1 % aller Requests) können Sie das Datenvolumen reduzieren, ohne die Sichtbarkeit zu verlieren. OpenTelemetry unterstützt konfigurierbare Sampling‑Strategien, die Sie in der TracerProvider‑Konfiguration festlegen.

7. Fazit und nächster Schritt

Sie haben nun ein funktionierendes FastAPI‑Projekt, das mit OpenTelemetry instrumentiert ist und innerhalb von 15 Minuten verteiltes Tracing liefert. Die Integration von Lescopr ermöglicht Ihnen sofortige Einblicke in Latenz, Fehlerraten und SLA‑Einhalten – alles in einem einheitlichen Dashboard.

Für mehr Details: Die Lescopr-Dokumentation beschreibt die Einrichtung Schritt für Schritt.