Una API FastAPI que se ralentiza sin dejar rastro es una pesadilla de guardia (on-call): los logs dicen «200 OK», los usuarios dicen «va lento». Instrumentar OpenTelemetry Python FastAPI te da trazas, métricas y un contexto compartido, sin instalar OneAgent en el host, algo que a menudo es imposible en un contenedor gestionado o en serverless.
Objetivo: al terminar este tutorial, tu servicio FastAPI envía sus spans y sus métricas por OTLP a Dynatrace, directamente o mediante un Collector, y sabes comprobar la ingesta. El contenido sirve tanto para Dynatrace SaaS (almacenamiento Grail, consultas DQL) como para Dynatrace Managed (endpoint OTLP del entorno, análisis en las pantallas clásicas). Las diferencias se señalan en cada paso.
Si al final tus spans no aparecen, ten a mano la guía de diagnóstico trazas de OpenTelemetry ausentes en Dynatrace.
El problema: una API de Python opaca
Sin instrumentación, una petición lenta se parece a todas las demás. No ves ni la llamada HTTP saliente de 800 ms ni la consulta SQL sin índice. El MTTR se alarga porque el equipo de guardia reconstruye el recorrido a mano. Con trazas, la duración de cada etapa se ve con un clic y puedes construir un SLI de latencia fiable.
Requisitos previos
- Python 3.10 o más reciente (mínimo exigido por las versiones actuales del SDK de OpenTelemetry), FastAPI y Uvicorn.
- Un entorno Dynatrace SaaS o Managed con la ingesta OTLP disponible.
- Un token de acceso de API con los scopes
openTelemetryTrace.ingest,metrics.ingestylogs.ingest(nombres que debes confirmar en tu pantalla de creación de tokens). - Opcional: un Collector de OpenTelemetry, recomendado en producción (consulta Collector de OpenTelemetry en Kubernetes).
Instrumentar OpenTelemetry Python FastAPI paso a paso
Paso 1: una aplicación mínima
# 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}
Paso 2: instalar los paquetes de 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
Punto crítico: usa el exportador HTTP/protobuf. El endpoint OTLP de Dynatrace acepta OTLP sobre HTTP; gRPC pasa por un Collector.
Paso 3: configurar la exportación hacia 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
Tres líneas merecen atención:
OTEL_EXPORTER_OTLP_HEADERS: el espacio entreApi-Tokeny el token se codifica como%20; de lo contrario, la cabecera se lee mal.OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta: Dynatrace espera métricas con temporalidad delta; en cumulative se rechazan. Detalles en temporalidad de las métricas OTLP.OTEL_SERVICE_NAME: es el nombre del servicio en Dynatrace. Sin él, obtienesunknown_service.
El exportador añade por sí mismo /v1/traces, /v1/metrics y /v1/logs al endpoint base. No los escribas en OTEL_EXPORTER_OTLP_ENDPOINT.
Para los logs, la antigua variable OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true activa el LoggingHandler del SDK, obsoleto desde opentelemetry-sdk 1.40. Con versiones recientes, déjala sin definir: la instrumentación logging instala su propio handler (se desactiva con OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false). En versiones más antiguas, la variable antigua sigue siendo necesaria.
Paso 4: lanzar la aplicación instrumentada
opentelemetry-instrument uvicorn main:app --host 0.0.0.0 --port 8000
No uses --reload con la autoinstrumentación: el proceso hijo que se relanza no siempre hereda la instrumentación. Con varios workers (Gunicorn), inicializa el SDK después del fork, en un hook post_fork; si no, los exportadores en segundo plano no funcionan correctamente.
Paso 5 (variante): instrumentación explícita en el código
Si prefieres controlar la inicialización, por ejemplo para añadir spans de negocio, configura el SDK en el código:
# 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}
Línea crítica: excluded_urls="health" retira las sondas de salud de las trazas. Falsean los percentiles de latencia y cuestan volumen para nada.
Paso 6: pasar por un Collector en producción
Apunta la aplicación al Collector local (http://otel-collector:4318) y deja que el Collector lleve el token. Ganas batching, reintentos y un único punto de configuración. El Collector exporta después con otlphttp:
exporters:
otlphttp/dynatrace:
endpoint: "https://<environment-id>.live.dynatrace.com/api/v2/otlp"
headers:
Authorization: "Api-Token ${env:DT_API_TOKEN}"
Cómo comprobar que funciona
- Lado aplicación: para una prueba local, añade
OTEL_TRACES_EXPORTER=otlp,console. Los spans se muestran en la salida estándar; si están ahí pero no en Dynatrace, el problema es la exportación (URL, token, proxy). - Genera tráfico:
for i in $(seq 1 20); do curl -s localhost:8000/orders/$i; done. - Dynatrace SaaS: abre la aplicación Distributed Tracing, filtra por el servicio
orders-api, o ejecuta en un notebook:fetch spans | filter service.name == "orders-api" | summarize count(), avg(duration), by: {span.name} - Dynatrace Managed: abre la vista de trazas distribuidas (nombre exacto según tu versión) y filtra por el servicio. El servicio OTel puede tardar unos minutos en aparecer.
- Errores HTTP: un código 401 o 403 en los logs del exportador indica un token o un scope incorrecto; un 404, una URL de endpoint errónea.
Buenas prácticas
- No mezcles OneAgent y el SDK de OTel en el mismo proceso sin pensarlo: riesgo de duplicados (consulta OneAgent y OpenTelemetry: duplicados de spans).
- Fija
service.name,service.versiony el entorno: hacen comparables los despliegues y aceleran el diagnóstico. - Mantén el token fuera del código: variable de entorno o secreto de Kubernetes.
- Relaciona tus logs con las trazas para pasar de un error a su petición: consulta logs de OpenTelemetry con trace_id.
- Construye un SLI de latencia sobre los spans de servidor y, después, una alerta de burn rate.
Preguntas frecuentes
¿Hace falta OneAgent para ver una aplicación FastAPI en Dynatrace?
No. La exportación OTLP basta para trazas, métricas y logs. OneAgent aporta además el descubrimiento automático del host y de los procesos; sin él, el enriquecimiento depende de los atributos de recurso que proporciones.
¿Por qué no llegan mis métricas si las trazas sí llegan?
Lo más habitual es que la temporalidad se haya quedado en cumulative o que el token no tenga el scope de ingesta de métricas. Revisa la variable de preferencia de temporalidad y los scopes.
¿Funciona la autoinstrumentación con Gunicorn y varios workers?
Sí, siempre que inicialices el SDK en cada worker después del fork. La documentación de OpenTelemetry Python describe este caso; pruébalo antes de pasar a producción.
Conclusión
Unas pocas variables de entorno y un comando de arranque bastan para hacer observable una API FastAPI en Dynatrace, tanto en SaaS como en Managed. Empieza por la autoinstrumentación, comprueba la ingesta y añade después spans de negocio donde el equipo de guardia los necesite. Para los detalles de los endpoints, consulta la documentación de Dynatrace sobre OpenTelemetry y la documentación de OpenTelemetry Python.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión.