OpenTelemetry Python FastAPI : instrumenter une API vers Dynatrace sans OneAgent

OpenTelemetry Python FastAPI : envoyez traces, métriques et logs en OTLP vers Dynatrace sans OneAgent, en SaaS ou Managed, puis vérifiez l’ingestion.
OpenTelemetry Python FastAPI : instrumenter une API vers Dynatrace sans OneAgent

Une API FastAPI qui ralentit sans laisser de trace est un cauchemar d’astreinte : les logs disent « 200 OK », les utilisateurs disent « c’est lent ». Instrumenter OpenTelemetry Python FastAPI vous donne des traces, des métriques et un contexte partagé, sans installer OneAgent sur l’hôte, ce qui est souvent impossible en conteneur géré ou en serverless.

Objectif : à la fin de ce tutoriel, votre service FastAPI envoie ses spans et ses métriques en OTLP vers Dynatrace, directement ou via un Collector, et vous savez vérifier l’ingestion. Le contenu vaut pour Dynatrace SaaS (stockage Grail, requêtes DQL) et pour Dynatrace Managed (endpoint OTLP de l’environnement, analyse dans les écrans classiques). Les différences sont signalées à chaque étape.

Si vos spans n’apparaissent pas à la fin, gardez sous la main le guide de diagnostic traces OpenTelemetry absentes dans Dynatrace.

Le problème : une API Python opaque

Sans instrumentation, une requête lente ressemble à toutes les autres. Vous ne voyez ni l’appel HTTP sortant de 800 ms, ni la requête SQL sans index. Le MTTR s’allonge parce que l’équipe de garde reconstruit le chemin à la main. Avec des traces, la durée de chaque étape est visible en un clic, et vous pouvez bâtir un SLI de latence fiable.

Prérequis

  • Python 3.10 ou plus récent (minimum exigé par les versions actuelles du SDK OpenTelemetry), FastAPI et Uvicorn.
  • Un environnement Dynatrace SaaS ou Managed avec l’ingestion OTLP disponible.
  • Un token d’accès API avec les scopes openTelemetryTrace.ingest, metrics.ingest et logs.ingest (noms à confirmer dans votre écran de création de token).
  • Optionnel : un Collector OpenTelemetry, recommandé en production (voir collector OpenTelemetry sur Kubernetes).

Instrumenter OpenTelemetry Python FastAPI pas à pas

Étape 1 : une application minimale

# main.py
from fastapi import FastAPI
import httpx

app = FastAPI()

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

@app.get("/orders/{order_id}")
async def get_order(order_id: int):
    async with httpx.AsyncClient() as client:
        r = await client.get("https://httpbin.org/delay/1")
    return {"order_id": order_id, "upstream": r.status_code}

Étape 2 : installer les paquets OpenTelemetry

pip install fastapi uvicorn httpx \
  opentelemetry-distro \
  opentelemetry-exporter-otlp-proto-http

# installe les instrumentations adaptées aux bibliothèques détectées
# (fastapi, httpx, requests, sqlalchemy...)
opentelemetry-bootstrap -a install

Point critique : utilisez l’exporteur HTTP/protobuf. L’endpoint OTLP de Dynatrace accepte OTLP sur HTTP ; le gRPC passe par un Collector.

Étape 3 : configurer l’export vers Dynatrace

export OTEL_SERVICE_NAME="orders-api"
export OTEL_RESOURCE_ATTRIBUTES="service.version=1.4.2,deployment.environment.name=prod"

# SaaS
export OTEL_EXPORTER_OTLP_ENDPOINT="https://<environment-id>.live.dynatrace.com/api/v2/otlp"
# Managed (à la place de la ligne précédente)
# export OTEL_EXPORTER_OTLP_ENDPOINT="https://<votre-domaine>/e/<environment-id>/api/v2/otlp"

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Api-Token%20<votre-token>"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE="delta"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"
# logs : le paquet opentelemetry-instrumentation-logging (installé par bootstrap)
# branche le handler par défaut dans les versions récentes

Trois lignes méritent attention :

  • OTEL_EXPORTER_OTLP_HEADERS : l’espace entre Api-Token et le token est encodé en %20, sinon l’en-tête est mal lu.
  • OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta : Dynatrace attend des métriques en temporalité delta ; en cumulative, elles sont rejetées. Détails dans temporalité des métriques OTLP.
  • OTEL_SERVICE_NAME : c’est le nom du service dans Dynatrace. Sans lui, vous obtenez unknown_service.

L’exporteur ajoute lui-même /v1/traces, /v1/metrics et /v1/logs à l’endpoint de base. Ne les écrivez pas dans OTEL_EXPORTER_OTLP_ENDPOINT.

Pour les logs, l’ancienne variable OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true active le LoggingHandler du SDK, déprécié depuis opentelemetry-sdk 1.40. Avec des versions récentes, laissez-la non définie : l’instrumentation logging installe son propre handler (désactivable avec OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false). Sur des versions plus anciennes, l’ancienne variable reste nécessaire.

Étape 4 : lancer l’application instrumentée

opentelemetry-instrument uvicorn main:app --host 0.0.0.0 --port 8000

N’utilisez pas --reload avec l’auto-instrumentation : le processus enfant relancé n’hérite pas toujours de l’instrumentation. Avec plusieurs workers (Gunicorn), initialisez le SDK après le fork, dans un hook post_fork, sinon les exporteurs en arrière-plan ne fonctionnent pas correctement.

Étape 5 (variante) : instrumentation explicite dans le code

Si vous préférez contrôler l’initialisation, par exemple pour ajouter des spans métier, configurez le SDK dans le code :

# telemetry.py
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.http.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

def setup_tracing(app):
    resource = Resource.create({
        "service.name": "orders-api",
        "service.version": "1.4.2",
    })
    provider = TracerProvider(resource=resource)
    # endpoint et en-têtes lus dans les variables OTEL_EXPORTER_OTLP_*
    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
    trace.set_tracer_provider(provider)
    FastAPIInstrumentor.instrument_app(app, excluded_urls="health")
    HTTPXClientInstrumentor().instrument()
# dans main.py
from opentelemetry import trace
from telemetry import setup_tracing

setup_tracing(app)
tracer = trace.get_tracer("orders")

@app.post("/orders")
async def create_order(payload: dict):
    with tracer.start_as_current_span("validate-order") as span:
        span.set_attribute("order.items", len(payload.get("items", [])))
    return {"created": True}

Ligne critique : excluded_urls="health" retire les sondes de santé des traces. Elles faussent les percentiles de latence et coûtent du volume pour rien.

Étape 6 : passer par un Collector en production

Pointez l’application vers le Collector local (http://otel-collector:4318) et laissez le Collector porter le token. Vous gagnez du batching, des retries et un seul point de configuration. Le Collector exporte ensuite avec otlphttp :

exporters:
  otlphttp/dynatrace:
    endpoint: "https://<environment-id>.live.dynatrace.com/api/v2/otlp"
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"

Comment vérifier que ça fonctionne

  1. Côté application : pour un test local, ajoutez OTEL_TRACES_EXPORTER=otlp,console. Les spans s’affichent dans la sortie standard ; s’ils y sont mais pas dans Dynatrace, le problème est l’export (URL, token, proxy).
  2. Générez du trafic : for i in $(seq 1 20); do curl -s localhost:8000/orders/$i; done.
  3. Dynatrace SaaS : ouvrez l’application Distributed Tracing, filtrez sur le service orders-api, ou lancez dans un notebook :
    fetch spans
    | filter service.name == "orders-api"
    | summarize count(), avg(duration), by: {span.name}
    
  4. Dynatrace Managed : ouvrez la vue des traces distribuées (nom exact selon votre version) et filtrez sur le service. Le service OTel peut mettre quelques minutes à apparaître.
  5. Erreurs HTTP : un code 401 ou 403 dans les logs de l’exporteur signale un token ou un scope incorrect ; un 404, une URL d’endpoint erronée.

Bonnes pratiques

  • Ne mélangez pas OneAgent et le SDK OTel sur le même processus sans réfléchir : risque de doublons (voir OneAgent et OpenTelemetry : doublons de spans).
  • Fixez service.name, service.version et l’environnement : ils rendent les déploiements comparables et accélèrent le diagnostic.
  • Gardez le token hors du code : variable d’environnement ou secret Kubernetes.
  • Reliez vos logs aux traces pour passer d’une erreur à sa requête : voir logs OpenTelemetry avec trace_id.
  • Construisez un SLI de latence sur les spans serveur, puis une alerte de burn rate.

Questions fréquentes

Faut-il OneAgent pour voir une application FastAPI dans Dynatrace ?

Non. L’export OTLP suffit pour les traces, les métriques et les logs. OneAgent apporte en plus la découverte automatique de l’hôte et des processus ; sans lui, l’enrichissement repose sur les attributs de ressource que vous fournissez.

Pourquoi mes métriques n’arrivent-elles pas alors que les traces arrivent ?

Le plus souvent, la temporalité est restée en cumulative ou le token n’a pas le scope d’ingestion des métriques. Vérifiez la variable de préférence de temporalité et les scopes.

L’auto-instrumentation fonctionne-t-elle avec Gunicorn et plusieurs workers ?

Oui, à condition d’initialiser le SDK dans chaque worker après le fork. La documentation OpenTelemetry Python décrit ce cas ; testez-le avant la production.

Conclusion

Quelques variables d’environnement et une commande de lancement suffisent pour rendre une API FastAPI observable dans Dynatrace, en SaaS comme en Managed. Commencez par l’auto-instrumentation, vérifiez l’ingestion, puis ajoutez des spans métier là où l’astreinte en a besoin. Pour les détails des endpoints, référez-vous à la documentation Dynatrace sur OpenTelemetry et à la documentation OpenTelemetry Python.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de son propriétaire.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Workflow Dynatrace Jira ou ServiceNow : ouvrir un ticket automatiquement sur problème

Workflow Dynatrace Jira ou ServiceNow : ouvrir un ticket automatiquement sur problème

Next Post
Migrer Managed vers SaaS : plan, outils et pièges de la bascule Dynatrace

Migrer Managed vers SaaS : plan, outils et pièges de la bascule Dynatrace

Related Posts