Observabilidade · infrastructure/observability
Adapter pronto para produçãoOpenTelemetry,
instrumentado no boot.
A auto-instrumentação só funciona se o SDK aplicar patch em Express, Prisma e companhia antes de eles carregarem. A UseDeploy faz do otel-init o primeiríssimo import no entrypoint do servidor — um requisito de ordem sutil que um setup feito na mão costuma errar.
O primeiro import vence
ESM faz hoisting das declarações de import acima do código do corpo, então startOtel precisa rodar como efeito colateral do primeiro import — não como uma chamada de função entre outros imports, o que anexaria as instrumentações tarde demais. otel-init.ts é esse primeiro import em 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
O que vem pronto
Traces OTLP
Os traces são exportados por OTLP HTTP quando OTEL_EXPORTER_OTLP_ENDPOINT está setada, e fazem no-op caso contrário — dev e CI nunca sobem exporters.
Métricas Prometheus
Um exporter Prometheus é exposto (e re-exposto via Express). As métricas estão ligadas por padrão; sete METRICS_ENABLED=false para desativar.
Auto-instrumentação
getNodeAutoInstrumentations aplica patch em Express, Prisma e HTTP. Se uma instrumentação se comportar mal no Bun, restrinja a config dela em vez de desativar o SDK.
Ordem correta, documentada
A ressalva sobre a ordem de imports é imposta pela estrutura e explicada no arquivo — a armadilha que produz traces vazios em silêncio fica fechada.
Referência de configuração
Variáveis de ambiente
OTEL_EXPORTER_OTLP_ENDPOINTopcionalunset → tracing off
OTEL_SERVICE_NAMEopcionalservice name on spans
METRICS_ENABLEDopcionaldefault true; set false to disable Prometheus
Onde ele vive
apps/server/src/bootstrap/otel.tsapps/server/src/otel-init.ts
Traces e métricas, conectados corretamente.
Publique com o OpenTelemetry subindo na ordem certa — ligue os exporters com uma env var quando estiver pronto.