OpenTelemetry Python FastAPI: instrumenta una API hacia Dynatrace sin OneAgent

OpenTelemetry Python FastAPI: envía trazas, métricas y logs por OTLP a Dynatrace sin OneAgent, en SaaS o Managed, y comprueba después la ingesta.
OpenTelemetry Python FastAPI : instrumenter une API vers Dynatrace sans OneAgent

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.ingest y logs.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 entre Api-Token y 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, obtienes unknown_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

  1. 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).
  2. Genera tráfico: for i in $(seq 1 20); do curl -s localhost:8000/orders/$i; done.
  3. 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}
    
  4. 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.
  5. 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.version y 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.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

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

Workflow de Dynatrace con Jira o ServiceNow: abrir un ticket automáticamente ante un problema

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

Migrar de Managed a SaaS: plan, herramientas y trampas del cambio en Dynatrace

Related Posts