Configuración - Python

Opciones que conviene conocer

Entornos

Cada entorno debería informar con un nombre inequívoco: production, staging, preview. El nombre es una columna del panel y un filtro de la lista de errores, así que sin él una caída de producción se ve igual que un error provocado en una prueba. Deja el entorno local sin credenciales: sin token ni clave la integración se carga y permanece en silencio, de modo que no necesitas desactivarla con una condición aparte.

Cuándo salen los eventos

El cliente nunca envía nada durante la parte de la petición que el visitante está esperando. send_later() programa un envío sin esperarlo: el método vuelve de inmediato y la tarea sigue corriendo en el bucle de eventos:

client.send_later(client.capture_exception(error))

La tarea se guarda en un conjunto interno hasta que termina: una corrutina referenciada solo por el bucle de eventos podría ser recogida por el recolector de basura a mitad de vuelo, lo que descartaría el evento en silencio. Un fallo se registra en el logger dock_ray en lugar de propagarse por la pila de llamadas: ninguna llamada a send_later() interrumpe la aplicación desde la que se está reportando.

El middleware ASGI funciona con el mismo ritmo: solo reporta una transacción una vez que la aplicación ha terminado de escribir la respuesta. Un panel lento o inaccesible no cuesta nada al visitante.

Middleware ASGI y FastAPI

El middleware abre una transacción por petición y reporta las excepciones no gestionadas. Está escrito contra la interfaz ASGI pura, no contra un framework concreto, así que funciona con FastAPI, Starlette y cualquier otra aplicación que hable ese protocolo, y no almacena en búfer las respuestas en streaming.

from fastapi import FastAPI
from dock_ray import DockRayClient, DockRayFastAPIMiddleware

client = DockRayClient(token="...", private_key="...")
app = FastAPI()

app.add_middleware(
    DockRayFastAPIMiddleware,
    client=client,
    exclude_paths=["/health", "/metrics"],
)

@app.on_event("shutdown")
async def shutdown() -> None:
    await client.close()

Cada petición se reporta junto con su método, ruta, duración y código de respuesta. exclude_paths omite por defecto /health y /metrics: rutas consultadas cada pocos segundos por la monitorización de infraestructura no deberían desplazar el tráfico real de la lista de transacciones. capture_transactions=False desactiva esa parte del middleware y deja solo el reporte de excepciones.

HTTPException es gestionada por el propio FastAPI y nunca llega al middleware como excepción: las respuestas esperadas 404 o 422 no se convierten en errores, sino que llegan al panel como transacciones con ese código de estado.

La dirección IP del visitante se lee de la cabecera X-Forwarded-For o X-Real-IP antes de recurrir a la dirección del socket: detrás de un balanceador de carga, ese socket pertenece al balanceador, no al visitante. Authorization, Cookie y X-Api-Key se eliminan de las cabeceras reportadas.

Transacciones manuales

Útiles para trabajo que ocurre fuera de una petición HTTP, por ejemplo un worker en segundo plano:

import time, uuid
from dock_ray import Span

started = time.time()
await run_daily_cleanup()
ended = time.time()

span = Span(
    span_id=uuid.uuid4().hex[:16],
    trace_id=uuid.uuid4().hex,
    start_timestamp=started,
    end_timestamp=ended,
    status="200",
    description="Daily cleanup",
    op="worker.task",
    data={"url": "job:daily_cleanup", "method": "CLI"},
)

await client.capture_transaction(name="job:daily_cleanup", spans=[span])

El span raíz - el que no tiene parent_span_id - lleva la URL, el método y el estado por los que el panel indexa la transacción. Sin esos tres campos en el span raíz, la transacción no tiene por qué aparecer en la lista.

Proteger la clave privada

La clave privada es un secreto del proyecto, no un identificador. Guárdala en variables de entorno, en un gestor de secretos o en la configuración del servidor: nunca en el repositorio, en los registros, en una captura de pantalla ni en código que llegue al navegador. Un proyecto puede tener varias claves, así que producción y preproducción deberían tener la suya: cada una se revoca por separado sin interrumpir a las demás. La sospecha de que una clave se ha filtrado ya es motivo suficiente para revocarla y generar otra.