obs-normalizer

Background service em Node.js que recebe webhooks de observabilidade (GlitchTip, Alertmanager), converte cada payload para o schema canônico ObsEvent, enriquece com sumário de trace (via Tempo) quando aplicável e publica no exchange RabbitMQ obs.events. Não possui UI — apenas endpoints HTTP de ingestão, probes de saúde e métricas Prometheus.

O que faz

• Recebe webhooks de fontes de observabilidade em endpoints HTTP autenticados.
• Converte cada payload bruto para o schema canônico ObsEvent usando receivers dedicados (parseGlitchTipWebhook, parseAlertmanagerWebhook).
• Quando o evento contém correlation.trace_id, busca um trace_summary em Tempo antes de publicar.
• Valida o ObsEvent resultante via Zod e publica no exchange RabbitMQ configurado.
• Expõe Swagger UI da API em /docs, spec OpenAPI em /openapi.json e métricas Prometheus em /metrics.

O serviço só atua como ingestor + publisher: o consumo dos eventos normalizados é responsabilidade de outros workers conectados ao mesmo exchange.

Inputs (webhooks)

Dois endpoints POST, cada um com seu próprio esquema de autenticação.

POST /webhooks/glitchtip

Recebe payloads do GlitchTip. A autenticação aceita o segredo por header x-webhook-secret ou query param ?secret=... (o GlitchTip só permite passar o segredo via URL).

curl -X POST https://obs-normalizer/webhooks/glitchtip?secret=$GLITCHTIP_WEBHOOK_SECRET \
  -H "Content-Type: application/json" \
  -d @glitchtip-payload.json

Respostas:

Quando o evento normalizado contém correlation.trace_id, o serviço chama Tempo (TEMPO_URL) para anexar um trace_summary antes de publicar.

POST /webhooks/alertmanager

Recebe payloads no formato Alertmanager webhook v4. Autenticação via HTTP Basic (ALERTMANAGER_USERNAME / ALERTMANAGER_PASSWORD).

curl -X POST https://obs-normalizer/webhooks/alertmanager \
  -u "$ALERTMANAGER_USERNAME:$ALERTMANAGER_PASSWORD" \
  -H "Content-Type: application/json" \
  -d @alertmanager-payload.json

Um payload Alertmanager pode gerar múltiplos ObsEvents. O serviço valida todos antes de publicar qualquer um — assim retries não causam publicação parcial.

Respostas:

Outputs (queue)

Os eventos normalizados são publicados no RabbitMQ, no exchange definido por RABBITMQ_EXCHANGE (default obs.events) dentro do vhost RABBITMQ_VHOST (default /obs). A publicação é feita por um ResilientPublisher configurado com a HTTP API do RabbitMQ:

new ResilientPublisher({
  publishOpts: {
    apiUrl: config.RABBITMQ_API_URL,
    user: config.RABBITMQ_USER,
    password: config.RABBITMQ_PASSWORD,
    vhost: config.RABBITMQ_VHOST,
    exchange: config.RABBITMQ_EXCHANGE,
  },
})

Cada mensagem segue o schema ObsEvent exportado por @simplafy-admin/obs-schema. O fluxo conceitual é:

webhook bruto → receiver dedicado → ObsEvent → (opcional) enrich com trace_summary → Zod validate → publish

Consumidores ligam suas filas a este exchange para reagir a eventos canônicos sem precisar conhecer o formato de cada fonte original.

Arquitetura em 1 parágrafo

O serviço é um app Fastify single-process. No bootstrap, instrument.js inicializa OpenTelemetry antes de qualquer outro import, e prom-client coleta métricas default do Node sob o prefixo obs_normalizer_. buildServer registra Swagger/Swagger UI, os health routes (/healthz, /readyz), os webhook routes (/webhooks/glitchtip, /webhooks/alertmanager) e expõe /openapi.json e /metrics. As rotas de webhook recebem um Publisher e um TraceFetcher por injeção de dependência: por padrão usam o ResilientPublisher (RabbitMQ HTTP API) e getTraceSummary (Tempo). Quando executado diretamente, o processo escuta em 0.0.0.0:PORT (default 3002).

Operação (health, metrics)

Health probes

{ "status": "ok", "version": "dev" }

{ "status": "ok", "tempo": true, "rabbitmq": true }

Métricas

GET /metrics expõe as métricas no formato Prometheus, incluindo as default do Node (process_*, nodejs_*) prefixadas com obs_normalizer_.

curl http://obs-normalizer:3002/metrics

Documentação interativa

• Swagger UI: /docs
• OpenAPI JSON: /openapi.json

Configuração

Variáveis lidas via Zod (src/config.ts); valores sem default são obrigatórios.