Pular para o conteúdo principal

Observability

Introdução ao documento​

Este documento descreve os sinais de observabilidade comprovados no repositório e as recomendações operacionais que podem ser derivadas deles sem inventar ferramentas externas. O foco está em logs, probes, métricas expostas pelo próprio app, RUM de frontend e pontos reais de inspeção.

Fato observado

  • O app expõe health, readiness e liveness.
  • O runtime registra eventos por console.log, console.warn e console.error.
  • O frontend inicializa Datadog RUM e o layout também injeta Meta Pixel em produção.

Evidências:

Versionamento​

Este documento deve ser atualizado quando houver mudança em:

  • formato e origem dos logs;
  • endpoints de saúde e probes do Helm;
  • SDKs de observabilidade no frontend;
  • variáveis de ambiente de telemetria;
  • regras operacionais recomendadas para alertas.

Evidências:

Referencial teórico​

Este documento usa apenas sinais que o código ou a infra local realmente expõem:

  • probes HTTP do próprio app;
  • logs de stdout/stderr gerados pelos handlers e adapters;
  • RUM client-side inicializado por código do repositório;
  • logs de pipeline GitHub Actions.

Inferência controlada

  • Como não há dashboards ou alertas versionados aqui, as recomendações abaixo são propostas operacionais derivadas dos sinais existentes, não um retrato de configuração já implantada.

Evidências:

Padrão de logs​

Formato observado​

Fato observado

  • O repositório não usa logger estruturado dedicado nem saída JSON padronizada.
  • O padrão predominante é console.error/console.warn/console.log com prefixos textuais.

Evidências:

Prefixos relevantes​

Prefixo / padrãoOrigem observadaUso operacional
[HTTP Timeout]fetchWithTimeoutdetectar integração externa lenta ou travada
[HTTP] ERROR ...fetchWithTimeoutdetectar falha de rede ou abort
[API] <status> ...adapters externosdetectar erro de backend por integração
[Auth] ...NextAuthdetectar sobrecarga e timeout de autenticação
[Health] System stuck.../api/healthdetectar degradação severa do processo
[Middleware Error] ...middleware.tsdetectar erro ao consultar modo manutenção

Evidências:

Healthchecks​

Endpoints expostos pelo app​

Fato observado

  • GET /api/health: health check geral com status, uptime, memória e métricas internas do processo.
  • GET /api/readiness: readiness baseado em variáveis obrigatórias, memória e uptime.
  • GET /api/liveness: liveness simples do processo.

Evidências:

Uso dos probes no Kubernetes​

Fato observado

  • O chart Helm usa /api/health para livenessProbe, readinessProbe e startupProbe.
  • O container expõe porta 3000, e o Service publica 80 -> 3000.

Divergência

  • Embora existam endpoints dedicados de readiness e liveness, o Deployment não os utiliza nas probes.

Evidências:

Métricas-chave​

Métricas diretamente expostas​

Fato observado

  • /api/health expõe:
    • status;
    • uptime.seconds e uptime.human;
    • memory.used, memory.total, memory.external, memory.usage;
    • metrics.totalRequests;
    • metrics.healthCheckCount;
    • metrics.timeSinceLastRequest;
    • metrics.healthCheckDuration;
    • metrics.consecutiveSlowChecks.
  • /api/readiness expõe estado de environment, memory e uptime.

Evidências:

Métricas/sinais de frontend observáveis​

Fato observado

  • O Datadog RUM é inicializado com trackUserInteractions, trackResources e trackLongTasks.
  • O endpoint /api/envs fornece appVersion, datadog.appId, clientToken, serviceName, env, sessionSampleRate e sessionReplaySampleRate.

Evidências:

Prioridade operacional sugerida​

Inferência controlada

  • Se a operação precisar escolher poucos sinais para monitorar primeiro, os mais críticos já expostos pelo app são:
    • health.status;
    • memory.usage;
    • healthCheckDuration;
    • consecutiveSlowChecks;
    • readiness.checks.environment;
    • erros [HTTP Timeout];
    • erros [Auth] Too many concurrent requests e [Auth] TIMEOUT after 15s.

Evidências:

Onde olhar logs​

1. Saída do processo da aplicação​

Fato observado

  • Os logs do runtime são emitidos por console.*, então o ponto primário de observação é stdout/stderr do processo Node que executa server.js.
  • Em Kubernetes, esse stdout/stderr pertence ao container definido no Deployment.

Evidências:

2. Logs do pipeline​

Fato observado

  • O build, push e deploy são executados por GitHub Actions; falhas nesses passos aparecem no log do workflow.

Evidências:

3. Console do navegador​

Fato observado

  • Problemas de bootstrap do Datadog e de configuração AMEI/Keycloak também aparecem no cliente.

Evidências:

Lacuna atual​

Fato observado

  • O repositório não versiona configuração de agregador de logs, dashboard, tracing distribuído ou alerta.

Evidências:

Alertas recomendados​

Inferência controlada

As recomendações abaixo derivam dos sinais já expostos pelo app e das falhas tratadas explicitamente pelo código.

Alertas de disponibilidade​

  • Alertar quando /api/health responder 503 ou status = "unhealthy".
  • Alertar quando /api/health responder status = "degraded" por janela contínua.
  • Alertar quando /api/readiness responder 503 ou status = "not_ready".

Evidências:

Alertas de saturação/memória​

  • Alertar quando memory.usage em /api/health ficar acima de 90%.
  • Alertar quando consecutiveSlowChecks >= 3.
  • Alertar quando readiness.checks.memory = false.

Evidências:

Alertas de integração​

  • Alertar em ocorrência recorrente de [HTTP Timeout].
  • Alertar em erros recorrentes de whats/otpSend, whats/sendFlowTemplate, wp/getCustomization, wp/getUserEnrollStatus, maintenance_mode.
  • Alertar em [Middleware Error] recorrente para capturar falha de consulta de manutenção.

Evidências:

Alertas de autenticação​

  • Alertar quando aparecer [Auth] Too many concurrent requests.
  • Alertar quando aparecer [Auth] TIMEOUT after 15s.
  • Alertar quando /api/config/keycloak responder 500 por configuração incompleta.

Evidências:

Alertas de telemetria frontend​

  • Alertar para ausência ou falha de configuração Datadog em ambientes onde RUM deveria estar ativo.
  • Tratar como pendência a divergência entre NEXT_DATADOG_CLIENT_ID no .env.example e NEXT_DATADOG_CLIENT_TOKEN usado pelo runtime.

Evidências:

Pendências​

  • Confirmar se há dashboards, centralização de logs e alertas fora deste repositório.
  • Confirmar se o uso de /api/health para todas as probes foi decisão intencional e permanente.
  • Resolver a divergência entre NEXT_DATADOG_CLIENT_ID e NEXT_DATADOG_CLIENT_TOKEN.

Evidências: