Introducción

En entornos de microservicios, la falta de trazas distribuidas dificulta la detección de cuellos de botella y aumenta el MTTR. Esta guía muestra, con ejemplos concretos, cómo integrar OpenTelemetry en una aplicación FastAPI y exportar los datos a Lescopr, obteniendo visibilidad completa sin sacrificar la performance.

Preparación del entorno

Requisitos previos

Python ≥ 3.9
FastAPI y Uvicorn
Acceso a una cuenta de Lescopr
Conexión a internet para descargar paquetes

Configuración del proyecto FastAPI

Crear un directorio y un entorno virtual:

mkdir fastapi-otel && cd fastapi-otel
python -m venv venv
source venv/bin/activate

Instalar FastAPI y Uvicorn:
```
pip install fastapi uvicorn
```

Crear main.py con un endpoint de ejemplo:

from fastapi import FastAPI
app = FastAPI()

@app.get("/ping")
async def ping():
    return {"msg": "pong"}

Ejecutar la aplicación:
```
uvicorn main:app --reload
```
Verifica que http://localhost:8000/ping devuelve {"msg":"pong"}.

Integración de OpenTelemetry

Instalación de dependencias

pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-fastapi opentelemetry-exporter-otlp

Configuración del tracer

Crea un archivo tracing.py y registra el tracer global:

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)

otlp_exporter = OTLPSpanExporter(endpoint="https://otel.lescopr.com/v1/traces")
span_processor = BatchSpanProcessor(otlp_exporter)
trace.get_tracer_provider().add_span_processor(span_processor)

En main.py importa y aplica la instrumentación:

from fastapi import FastAPI
from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
from tracing import tracer

app = FastAPI()
FastAPIInstrumentor().instrument_app(app)

¿Qué es OpenTelemetry? OpenTelemetry es un proyecto de código abierto que define estándares y APIs para la instrumentación de aplicaciones, permitiendo la captura de métricas, logs y trazas de forma unificada.

Envío de datos a Lescopr

Configuración del exportador Lescopr

Lescopr expone un endpoint OTLP compatible. Ajusta la URL y el token de autenticación en tracing.py:

from opentelemetry.sdk.resources import Resource
from opentelemetry.semconv.resource import ResourceAttributes

resource = Resource(attributes={
    ResourceAttributes.SERVICE_NAME: "fastapi-demo",
    ResourceAttributes.SERVICE_NAMESPACE: "backend",
    "environment": "production"
})

trace.set_tracer_provider(TracerProvider(resource=resource))

Asegúrate de definir la variable de entorno LESCOPR_OTLP_TOKEN con tu clave API.

Verificación en el dashboard

Inicia la aplicación con la variable de entorno:

export LESCOPR_OTLP_TOKEN=your_api_key
uvicorn main:app --reload

Genera tráfico contra /ping y cualquier endpoint adicional.
Accede al panel de Lescopr → Tracing. Deberías ver spans con nombres de ruta, latencias y códigos de estado.

Mejores prácticas y depuración

Métricas clave a monitorizar

Latencia media por endpoint
Tasa de error (5xx)
Duración de spans críticos (bases de datos, llamadas externas)
Throughput de requests por segundo

Manejo de errores y sobrecarga

Usa try/except alrededor de llamadas externas y registra excepciones como eventos en el span.

Limita el muestreo en entornos de alta carga para evitar sobrecargar la red:

from opentelemetry.sdk.trace.sampling import TraceIdRatioBased
trace.get_tracer_provider().sampler = TraceIdRatioBased(0.5)  # 50% de los requests

Revisa el CPU overhead con top o htop; la instrumentación típica añade <5 % de carga.

Conclusión

Integrar trazas distribuidas en FastAPI con OpenTelemetry y Lescopr es un proceso directo que aporta visibilidad de extremo a extremo, reduce el MTTR y permite cumplir SLA más estrictos. La configuración mínima se completa en minutos y se adapta a cualquier stack basado en Python.

Para profundizar, la documentación de Lescopr detalla la implementación paso a paso.