Pular para o conteúdo principal

Observabilidade

Introdução ao documento​

Este documento descreve o que já existe de observabilidade no serviço (logs e probes) e os pontos que ainda precisam de formalização. Evidência: src/server.ts:52 Evidência: src/server.ts:168

Versionamento​

  • Versão do documento: 2.0.0.
  • Última atualização: 2026-03-18. Evidência: codex-promts.md:16

Referencial teórico​

  • Healthchecks HTTP usados em Kubernetes.
  • Logging estruturado mínimo orientado a troubleshooting. Evidência: helm/templates/deployment.yaml:53 Evidência: src/server.ts:62

Padrão de logs​

Logs implementados no código​

  • Log de entrada HTTP com método, path, query, body (exceto GET) e mascaramento do header authorization.
  • Logs de erro global (unhandledRejection, uncaughtException, middleware de erro).
  • Logs específicos do worker de fila (warn/error por retry e falha definitiva). Evidência: src/server.ts:62 Evidência: src/server.ts:67 Evidência: src/server.ts:18 Evidência: src/server.ts:263 Evidência: src/workers/groupLinkDispatchWorker.ts:145

Lacunas observadas​

  • Não há request-id padronizado nem correlação distribuída.
  • Não há biblioteca de métricas/telemetria (OpenTelemetry, Prometheus client) no package.json. Evidência: src/server.ts:62 Evidência: package.json:14

Healthchecks​

  • GET /api/liveness: retorna status: ok.
  • GET /api/readiness: valida db.authenticate() e retorna 200 ou 503.
  • Helm configura livenessProbe e readinessProbe usando esses endpoints. Evidência: src/server.ts:168 Evidência: src/server.ts:176 Evidência: src/server.ts:180 Evidência: helm/templates/deployment.yaml:53 Evidência: helm/templates/deployment.yaml:59

Métricas-chave​

Disponíveis de forma indireta (via logs/endpoints)​

  • Taxa de erro HTTP (500, 503, 404) observável em respostas e logs.
  • Saúde do banco pelo readiness.
  • Taxa de falha da fila pelo volume de retries/falhas no worker. Evidência: src/server.ts:265 Evidência: src/server.ts:192 Evidência: src/server.ts:275 Evidência: src/workers/groupLinkDispatchWorker.ts:130

Recomendadas para evolução​

  • Latência p95/p99 por rota.
  • Throughput por endpoint.
  • Profundidade da fila (pending, processing, failed). Evidência: src/workers/groupLinkDispatchWorker.ts:56 Evidência: src/models/groupLinkDispatchQueue.ts:87

Onde olhar logs​

  • Execução local Node: terminal do processo iniciado por npm run dev/npm run start.
  • Execução Docker local: docker compose logs -f onboarding-api.
  • Kubernetes: kubectl logs no deployment do chart. Evidência: package.json:8 Evidência: docker-compose.yml:6 Evidência: helm/templates/deployment.yaml:36

Alertas recomendados​

  • Readiness 503 contínuo por mais de 5 minutos.
  • Taxa de erro 5xx acima do baseline por janela de 5 minutos.
  • Crescimento de jobs failed na GroupLinkDispatchQueue.
  • Falha recorrente de assinatura/criptografia no POST /.
  • Falha de validação de webhook (403 em GET /webhook). Evidência: src/server.ts:192 Evidência: src/server.ts:265 Evidência: src/models/groupLinkDispatchQueue.ts:87 Evidência: src/encryption.ts:45 Evidência: src/routes/webhook.ts:95

Pendências​

  • Confirmar stack oficial de monitoramento/alerta (Grafana, Datadog, CloudWatch etc.), pois não há referência explícita no código.
  • Confirmar retenção e destino de logs em produção. Evidência: package.json:14 Evidência: .github/workflows/ci-cd-pipeline.yml:69