Observabilidad · infrastructure/observability
Adapter listo para producciónOpenTelemetry,
instrumentado en el arranque.
La auto-instrumentación solo funciona si el SDK parchea Express, Prisma y compañía antes de que carguen. UseDeploy hace de otel-init el primerísimo import en el entrypoint del servidor — un requisito de orden sutil que un setup armado a mano suele equivocar.
El primer import gana
ESM sube (hoisting) las declaraciones de import por encima del código del cuerpo, así que startOtel tiene que correr como efecto secundario del primer import — no como una llamada a función entre otros imports, lo que engancharía las instrumentaciones demasiado tarde. otel-init.ts es ese primer import en index.ts.
1 // index.ts — this MUST be the first import:
2 import './otel-init.js';
3
4 // otel-init.ts — starts OTel as a side effect of evaluation:
5 export const otel = startOtel(); // OTLP traces + Prometheus metrics
Lo que viene listo
Trazas OTLP
Las trazas se exportan por OTLP HTTP cuando OTEL_EXPORTER_OTLP_ENDPOINT está seteada, y hacen no-op si no — dev y CI nunca levantan exporters.
Métricas Prometheus
Se expone un exporter de Prometheus (y se re-expone vía Express). Las métricas están encendidas por defecto; seteá METRICS_ENABLED=false para desactivarlas.
Auto-instrumentación
getNodeAutoInstrumentations parchea Express, Prisma y HTTP. Si una instrumentación se comporta mal en Bun, acotá su config en vez de desactivar el SDK.
Orden correcto, documentado
La advertencia sobre el orden de imports se impone por estructura y se explica en el archivo — la trampa que produce trazas vacías en silencio queda cerrada.
Referencia de configuración
Variables de entorno
OTEL_EXPORTER_OTLP_ENDPOINTopcionalunset → tracing off
OTEL_SERVICE_NAMEopcionalservice name on spans
METRICS_ENABLEDopcionaldefault true; set false to disable Prometheus
Dónde vive
apps/server/src/bootstrap/otel.tsapps/server/src/otel-init.ts
Trazas y métricas, cableadas correctamente.
Shippeá con OpenTelemetry arrancando en el orden correcto — encendé los exporters con una env var cuando estés listo.