OpenTelemetry¶

Lorsque votre API est en cours d'exécution, vous pouvez vouloir savoir quel trafic elle reçoit, quelles requêtes sont lentes et quand des erreurs se produisent.

La télémétrie désigne les données sur le comportement de votre application qui vous aident à répondre à ces questions. Les types courants comprennent :

• Métriques : des mesures que vous pouvez agréger au fil du temps, comme les temps de réponse et le nombre de requêtes en cours de traitement.
• Traces : des enregistrements de requêtes individuelles et des opérations effectuées pour les traiter. Chaque opération chronométrée est appelée un span.
• Logs : des enregistrements horodatés d'événements, comme le démarrage d'une application ou l'échec d'une opération.

OpenTelemetry est un ensemble de standards et d'outils permettant de collecter la télémétrie et de l'envoyer à un service de supervision, où vous pouvez l'explorer dans des tableaux de bord.

FastAPI prend en charge OpenTelemetry par défaut pour les traces, les métriques et les logs des requêtes HTTP. Les connexions WebSocket fournissent également des traces et des logs. Pour consulter ces données, configurez un service de supervision pour les recevoir.

Installer FastAPI¶

Installez FastAPI avec les dépendances optionnelles standard, qui incluent les paquets permettant d'envoyer la télémétrie :

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

Créer l'application¶

Créez un fichier 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}

Remarquez que tout fonctionne par défaut : vous n'avez pas besoin d'écrire de code personnalisé pour que la télémétrie fonctionne.

FastAPI Cloud¶

Lorsque vous déployez sur FastAPI Cloud avec fastapi[standard], les métriques fonctionnent automatiquement. Vous n'avez rien d'autre à configurer.

Avec les offres Pro, vous pouvez consulter le nombre de requêtes, les taux d'erreur et les temps de réponse dans le tableau de bord des métriques.

Autres services de supervision¶

Pour envoyer la télémétrie à un autre service de supervision, configurez un endpoint qui accepte OTLP, le protocole OpenTelemetry pour l'envoi de télémétrie. Utilisez l'endpoint de base HTTP/protobuf du service.

Définissez ces variables d'environnement en remplaçant l'URL d'exemple par votre endpoint :

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

OTEL_SERVICE_NAME identifie votre application dans le service de supervision. L'endpoint est l'URL de base pour recevoir les données. Les traces sont envoyées à /v1/traces, les métriques à /v1/metrics et les logs à /v1/logs sous cette URL.

Si votre service nécessite une authentification, définissez OTEL_EXPORTER_OTLP_HEADERS avec les en-têtes qu'il spécifie, par exemple api-key=YOUR_API_KEY.

Exécuter l'application¶

Démarrez l'application dans le même terminal :

$ uv run fastapi run

Dans un autre terminal, envoyez une requête :

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

Ouvrez votre service de supervision et recherchez my-api. Après le prochain export, vous pouvez voir une trace avec un span GET /items/{item_id}, ainsi que des métriques sur le nombre de requêtes, la durée des réponses et les requêtes actives.

Personnaliser la télémétrie¶

Configurer les fournisseurs et les exportateurs¶

Un fournisseur fournit les objets qui enregistrent les traces, les métriques ou les logs. Sa configuration contrôle la façon dont ces données sont traitées et exportées.

Les bibliothèques de télémétrie peuvent configurer les fournisseurs globaux d'OpenTelemetry. Configurez la bibliothèque avant le démarrage de l'application, et FastAPI utilise automatiquement ces fournisseurs.

Lorsqu'un endpoint OTLP est défini dans l'environnement, FastAPI ajoute un exportateur pour cette destination à chaque fournisseur activé. Les exportateurs existants continuent d'envoyer des données vers leurs destinations.

Configurez chaque destination une seule fois. Si une autre bibliothèque gère déjà la destination définie dans l'environnement, désactivez son export vers cette destination ou désactivez la configuration automatique de FastAPI :

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

Vous pouvez aussi passer un fournisseur directement dans le dictionnaire telemetry. Par exemple, ce fournisseur utilise l'exportateur console d'OpenTelemetry pour afficher les spans des requêtes dans votre terminal :

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}

L'exportateur envoie les spans vers leur destination. BatchSpanProcessor regroupe les spans et les envoie en arrière-plan. Remplacez l'exportateur console par un exportateur fourni par votre bibliothèque de supervision pour utiliser sa destination. Consultez le guide d'instrumentation Python d'OpenTelemetry pour plus d'options de configuration.

Utilisez meter_provider ou logger_provider dans le même dictionnaire pour fournir un fournisseur de métriques ou de logs. L'application ou la bibliothèque qui crée un fournisseur gère son arrêt. FastAPI gère les composants d'export qu'il ajoute.

Tracer les opérations des requêtes¶

Par défaut, les traces des requêtes incluent des spans pour la résolution des dépendances, l'exécution de votre fonction de chemin d'accès, la sérialisation de la réponse et l'exécution de chaque tâche dans BackgroundTasks de FastAPI. Ces spans utilisent le même fournisseur et les mêmes exportateurs.

Les spans des tâches en arrière-plan font toujours partie de la trace de la requête. Ils s'exécutent après la fin du span de la réponse HTTP et n'augmentent donc pas le temps de réponse mesuré.

Pour enregistrer uniquement le span de la requête HTTP, définissez operation_spans sur 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}

Tracer les connexions WebSocket¶

Chaque connexion WebSocket possède un span tel que WS /ws/{room}, qui couvre le gestionnaire et le nettoyage des dépendances. Il utilise les mêmes fournisseurs et paramètres, notamment operation_spans pour la résolution des dépendances et l'exécution de l'endpoint.

Les métriques des requêtes HTTP couvrent uniquement les requêtes HTTP. Les déconnexions WebSocket normales avec les codes 1000 ou 1001 ne produisent pas de logs d'erreur.

Examiner les erreurs¶

FastAPI enregistre les exceptions non gérées sous forme de logs OpenTelemetry, liés à la trace de la requête ou de la connexion. Les logs d'erreur sont enregistrés même lorsque la trace n'est pas échantillonnée.

Les logs d'exception incluent le type, le message et la trace de pile de l'exception. Les messages et les traces de pile peuvent contenir des informations sensibles. Utilisez les processeurs de logs de votre fournisseur pour les filtrer ou masquer ces informations, ou définissez logs sur False pour désactiver ces logs.

FastAPI enregistre également les échecs de validation des requêtes sous forme de logs d'avertissement avec la route et le nombre d'erreurs. Ces logs n'incluent pas les données d'entrée invalides.

Choisir les données à enregistrer¶

Le dictionnaire telemetry accepte également ces paramètres :

Par exemple, pour collecter des métriques tout en excluant les vérifications de l'état de santé :

from fastapi import FastAPI

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

Définissez auto_configure sur False lorsque votre application gère elle-même la configuration des fournisseurs, par exemple dans sa fonction lifespan.