OpenTelemetry¶

Wenn Ihre API läuft, möchten Sie vielleicht wissen, wie viel Traffic sie erhält, welche Requests langsam sind und wann Fehler auftreten.

Telemetrie umfasst Daten über das Verhalten Ihrer Anwendung, die Ihnen helfen, diese Fragen zu beantworten. Zu den gängigen Typen gehören:

• Metriken: Messwerte, die Sie über einen Zeitraum zusammenfassen können, etwa Responsezeiten und die Anzahl der verarbeiteten Requests.
• Traces: Aufzeichnungen einzelner Requests und der Operationen, die zu ihrer Verarbeitung ausgeführt werden. Jede zeitlich erfasste Operation wird als Span bezeichnet.
• Logs: Aufzeichnungen von Events mit Zeitstempel, etwa das Starten einer Anwendung oder das Fehlschlagen einer Operation.

OpenTelemetry ist eine Sammlung von Standards und Werkzeugen zum Erfassen von Telemetriedaten und zum Senden dieser Daten an einen Monitoring-Dienst, wo Sie sie in Dashboards untersuchen können.

FastAPI bietet standardmäßig OpenTelemetry-Unterstützung für HTTP-Request-Traces, Metriken und Logs. WebSocket-Verbindungen liefern ebenfalls Traces und Logs. Um diese Daten anzuzeigen, konfigurieren Sie einen Monitoring-Dienst, der sie empfängt.

FastAPI installieren¶

Installieren Sie FastAPI mit den standard-Extras, die die Pakete zum Senden von Telemetriedaten enthalten:

$ uv add "fastapi[standard]"
---> 100%

Die Anwendung erstellen¶

Erstellen Sie eine Datei main.py:

from fastapi import FastAPI

app = FastAPI()


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Sie müssen keinen eigenen Code schreiben, um Telemetriedaten zu erfassen.

FastAPI Cloud¶

Wenn Sie mit fastapi[standard] auf FastAPI Cloud deployen, funktionieren Metriken automatisch. Sie müssen nichts weiter konfigurieren.

Mit einem Pro-Tarif können Sie die Anzahl der Requests, Fehlerraten und Responsezeiten im Metriken-Dashboard anzeigen.

Andere Monitoring-Dienste¶

Um Telemetriedaten an einen anderen Monitoring-Dienst zu senden, konfigurieren Sie einen Endpunkt, der OTLP akzeptiert, das OpenTelemetry-Protokoll zum Senden von Telemetriedaten. Verwenden Sie den HTTP/protobuf-Basisendpunkt des Dienstes.

Setzen Sie diese Umgebungsvariablen und ersetzen Sie die Beispiel-URL durch Ihren Endpunkt:

export FASTAPI_OTEL_AUTO_CONFIGURE=true
export OTEL_SERVICE_NAME=my-api
export OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com

FASTAPI_OTEL_AUTO_CONFIGURE=true aktiviert FastAPIs automatische Einrichtung der Exporter. OTEL_SERVICE_NAME identifiziert Ihre Anwendung im Monitoring-Dienst. Der Endpunkt ist die Basis-URL für den Empfang von Daten. Unter dieser URL werden Traces an /v1/traces, Metriken an /v1/metrics und Logs an /v1/logs gesendet.

Wenn Ihr Dienst Authentifizierung erfordert, setzen Sie OTEL_EXPORTER_OTLP_HEADERS auf die von ihm vorgegebenen Header, zum Beispiel api-key=YOUR_API_KEY.

Die Anwendung ausführen¶

Starten Sie die Anwendung im selben Terminal:

$ uv run fastapi run

Senden Sie in einem anderen Terminal einen Request:

$ curl http://127.0.0.1:8000/items/1
{"item_id":1}

Öffnen Sie Ihren Monitoring-Dienst und suchen Sie nach my-api. Nach dem nächsten Export sehen Sie einen Trace mit einem GET /items/{item_id}-Span sowie Metriken zur Anzahl der Requests, zur Responsedauer und zu aktiven Requests.

Telemetrie anpassen¶

Provider und Exporter konfigurieren¶

Ein Provider stellt die Objekte bereit, die Traces, Metriken oder Logs aufzeichnen. Seine Konfiguration steuert, wie diese Daten verarbeitet und exportiert werden.

Telemetriebibliotheken können die globalen Provider von OpenTelemetry konfigurieren. Konfigurieren Sie die Bibliothek, bevor die Anwendung startet, und FastAPI verwendet diese Provider automatisch.

Standardmäßig verwendet FastAPI konfigurierte Provider, ohne Exporter hinzuzufügen. Wenn die automatische Einrichtung aktiviert und ein OTLP-Endpunkt in der Umgebung gesetzt ist, fügt FastAPI jedem aktivierten Provider einen Exporter für dieses Ziel hinzu. Vorhandene Exporter senden weiterhin Daten an ihre Ziele.

Wenn eine andere Bibliothek bereits den Export an dasselbe Ziel konfiguriert, lassen Sie FASTAPI_OTEL_AUTO_CONFIGURE ungesetzt oder setzen Sie die Variable auf false, um doppelte Telemetriedaten zu vermeiden.

Sie können auch einen Provider direkt im Dictionary telemetry übergeben. Dieser Provider verwendet beispielsweise den Konsolenexporter von OpenTelemetry, um Request-Spans in Ihrem Terminal auszugeben:

from fastapi import FastAPI
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

app = FastAPI(telemetry={"tracer_provider": tracer_provider})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

Der Exporter sendet die Spans an ihr Ziel. BatchSpanProcessor gruppiert Spans und sendet sie im Hintergrund. Ersetzen Sie den Konsolenexporter durch einen Exporter Ihrer Monitoring-Bibliothek, um deren Ziel zu verwenden. Weitere Konfigurationsoptionen finden Sie im Leitfaden zur Python-Instrumentierung von OpenTelemetry.

Verwenden Sie meter_provider oder logger_provider im selben Dictionary, um einen Provider für Metriken oder Logs bereitzustellen. Die Anwendung oder Bibliothek, die einen Provider erstellt, verwaltet dessen Shutdown. FastAPI verwaltet die Exportkomponenten, die es hinzufügt.

Request-Operationen nachverfolgen¶

Standardmäßig enthalten Request-Traces Spans für das Auflösen von Abhängigkeiten, das Ausführen Ihrer Pfadoperation-Funktion, das Serialisieren der Response und das Ausführen jedes Tasks in FastAPIs BackgroundTasks. Diese Spans verwenden denselben Provider und dieselben Exporter.

Die Spans der Hintergrundtasks bleiben Teil des Request-Traces. Sie werden ausgeführt, nachdem der HTTP-Response-Span beendet ist, und erhöhen daher nicht die gemessene Responsezeit.

Um nur den HTTP-Request-Span aufzuzeichnen, setzen Sie operation_spans auf False:

from fastapi import FastAPI

app = FastAPI(telemetry={"operation_spans": False})


@app.get("/items/{item_id}")
async def read_item(item_id: int):
    return {"item_id": item_id}

WebSocket-Verbindungen nachverfolgen¶

Jede WebSocket-Verbindung hat einen Span wie WS /ws/{room}, der den Handler und das Aufräumen der Abhängigkeiten umfasst. Er verwendet dieselben Provider und Einstellungen, einschließlich operation_spans für das Auflösen von Abhängigkeiten und das Ausführen des Endpunkts.

HTTP-Request-Metriken erfassen nur HTTP-Requests. Normale WebSocket-Verbindungsabbrüche mit den Codes 1000 oder 1001 erzeugen keine Fehlerlogs.

Fehler untersuchen¶

FastAPI zeichnet unbehandelte Exceptions als OpenTelemetry-Logs auf, die mit dem Trace des Requests oder der Verbindung verknüpft sind. Fehlerlogs werden auch dann aufgezeichnet, wenn der Trace nicht durch Sampling erfasst wird.

Exception-Logs enthalten den Typ, die Nachricht und den Stacktrace der Exception. Nachrichten und Stacktraces können sensible Informationen enthalten. Verwenden Sie die Logprozessoren Ihres Providers, um diese zu filtern oder zu schwärzen, oder setzen Sie logs auf False, um diese Logs zu deaktivieren.

FastAPI zeichnet außerdem fehlgeschlagene Request-Validierungen als Warnungslogs mit der Route und der Fehleranzahl auf. Diese Logs enthalten nicht die ungültigen Eingabedaten.

Die aufzuzeichnenden Daten auswählen¶

Das Dictionary telemetry akzeptiert außerdem diese Einstellungen:

Um beispielsweise Metriken zu erfassen und dabei Healthchecks auszuschließen:

from fastapi import FastAPI

app = FastAPI(
    telemetry={
        "tracing": False,
        "exclude": lambda scope: scope["path"] == "/health",
    }
)

Ein expliziter Wert für auto_configure im Dictionary telemetry überschreibt FASTAPI_OTEL_AUTO_CONFIGURE. Verwenden Sie telemetry={"auto_configure": True}, um die automatische Einrichtung im Code zu aktivieren, oder telemetry={"auto_configure": False}, um sie für eine Anwendung zu deaktivieren, selbst wenn die Umgebungsvariable sie aktiviert.