@ciag/observability

Observabilidade padrão CIAg para NestJS (@ciag/observability/nest) e Angular (@ciag/observability/angular). O app fala só padrões abertos — OpenTelemetry (OTLP) para traces/métricas/logs e protocolo Sentry para erros —, então trocar a plataforma (Grafana ↔ SigNoz, GlitchTip ↔ Sentry) é configuração, nunca código do app.

Desligado sem configuração. Sem OTEL_EXPORTER_OTLP_ENDPOINT nada é exportado (e o SDK do OpenTelemetry nem é carregado); sem ERRORS_DSN nenhum erro é enviado (o Sentry nem é carregado). Local = custo zero e zero aviso.
Nunca derruba o app. Coletor/GlitchTip fora do ar, URL ou DSN inválidos: a API sobe e responde; só um aviso no log (no máximo 1 por minuto por motivo).
PII não sai do app (LGPD) — ver LGPD.

Instalação em 10 minutos

Back (NestJS 11)

npm i @ciag/observability \
  @opentelemetry/api @opentelemetry/api-logs @opentelemetry/core @opentelemetry/resources \
  @opentelemetry/semantic-conventions @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base \
  @opentelemetry/sdk-metrics @opentelemetry/sdk-logs @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/exporter-metrics-otlp-http @opentelemetry/exporter-logs-otlp-http \
  @opentelemetry/instrumentation @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express \
  @opentelemetry/instrumentation-nestjs-core @opentelemetry/instrumentation-mysql2 \
  @prisma/instrumentation@<mesma versão do prisma> @sentry/nestjs pino

(As dependências de cada lado são peerDependencies opcionais: quem usa só o Nest não instala Angular, e vice-versa. As versões testadas estão em devDependencies deste pacote.)

src/instrumentation.ts (arquivo próprio, carregado ANTES do Nest):

import { initTelemetry } from '@ciag/observability/nest';
// Padrões do código; OTEL_SERVICE_NAME / APP_RELEASE / DEPLOYMENT_ENVIRONMENT têm prioridade.
initTelemetry({ serviceName: 'teatime-api', serviceVersion: pkg.version });

Primeira linha do src/main.ts: import './instrumentation'; e o logger JSON no create:

import './instrumentation';
import { observabilityLogger } from '@ciag/observability/nest';
const app = await NestFactory.create(AppModule, { logger: observabilityLogger() });

AppModule: imports: [ObservabilityModule.forRoot(), ...].

CORS (front em outra origem): permita os cabeçalhos de trace e exponha o request id:

allowedHeaders: [...os atuais, 'traceparent', 'tracestate', 'baggage', 'sentry-trace', 'X-Request-Id'],
exposedHeaders: ['X-Request-Id'],

Front (Angular 19–22, standalone)

npm i @ciag/observability @sentry/angular

// app.config.ts
provideObservability({
  serviceName: 'teatime-web',
  release: VERSION,
  environment: environment.DEPLOYMENT_ENVIRONMENT, // 'prod' | 'hml' | 'local'
  errorsDsn: environment.ERRORS_DSN,               // '' = desligado
  apiOrigins: [environment.API_URL],               // SÓ estes recebem traceparent
  tracesSampleRate: 0.2,
}),

Mensagem de erro de API: errorReference(err) devolve o errorId (ou o X-Request-Id) para mostrar "Código do erro: …".
Login: setObservabilityUser(userId); logout: clearObservabilityUser().

Sem DSN, provideObservability devolve uma lista vazia de providers (o app fica idêntico). Com DSN, o SDK do Sentry vem num chunk separado carregado depois do bootstrap — não pesa no JS inicial. Erros anteriores ao carregamento ficam numa fila (até 20) e são enviados quando o SDK chega.

O que cada lado faz