Pular para o conteúdo principal

Observabilidade

Introdução ao documento​

Este documento registra apenas os mecanismos de observabilidade que possuem evidência no repositório: probes HTTP, telemetria browser com Datadog, Google Analytics, logs por console.*, envio de logs de negócio ao backend e logs operacionais dos workflows GitHub Actions. Onde houver recomendação operacional, ela será marcada como inferência.

Fato observado:

  • A aplicação expõe rotas /api/health, /api/liveness e /api/readiness. Evidências: src/app/api/health/route.ts:3-31, src/app/api/liveness/route.ts:3-11, src/app/api/readiness/route.ts:3-23.
  • O cliente inicializa datadogRum e datadogLogs a partir de /api/envs. Evidências: src/app/start/DatadogStart.tsx:11-47, src/app/api/envs/route.ts:6-26.
  • O layout injeta Google Analytics. Evidências: src/app/layout.tsx:6, src/app/layout.tsx:51, src/app/layout.tsx:81-90.

Versionamento​

  • Documento atualizado em 2026-03-20.
  • Revisar quando mudarem bootstrap de telemetria, endpoints de healthcheck, naming de envs ou fluxos de deploy.

Fato observado:

  • A aplicação versionada no repositório está em 0.1.4. Evidências: package.json:2-3.
  • O healthcheck inclui campo de versão baseado em NEXT_APP_VERSION. Evidências: src/app/api/health/route.ts:6-19.

Referencial teórico​

O referencial teórico adotado aqui é o que o próprio repositório implementa: health/liveness/readiness em HTTP, telemetria client-side orientada a RUM/logs, e logs técnicos por console.* em rotas, hooks e serviços.

Fato observado:

  • Docker usa HEALTHCHECK contra /api/health. Evidências: Dockerfile:72-74.
  • Kubernetes usa livenessProbe e readinessProbe contra /api/liveness e /api/readiness. Evidências: helm/templates/deployment.yaml:53-64.
  • O browser bootstrap ativa trackUserInteractions, trackResources e trackLongTasks no Datadog RUM. Evidências: src/app/start/DatadogStart.tsx:19-32.

Padrão de logs​

1. Logs técnicos por console.*​

Fato observado:

  • As rotas de API e serviços usam console.error para falhas operacionais. Exemplos: src/app/api/health/route.ts:20-30, src/app/api/submissions/route.ts:21-37, src/app/api/submissions/route.ts:73-89, src/app/api/jitsi/config/route.ts:11-17, src/services/StatusService.ts:79-83.
  • Há logs de depuração em integrações de quiz e cache em memória. Exemplos: src/services/quizApi.ts:65-77, src/services/quizApi.ts:197, src/hooks/useGetDataWithCache.ts:5-24.

2. Logs browser enviados ao Datadog​

Fato observado:

  • datadogLogs.init é chamado com forwardErrorsToLogs: true. Evidências: src/app/start/DatadogStart.tsx:34-41.
  • A inicialização usa clientToken, env, version e sessionSampleRate vindos de /api/envs. Evidências: src/app/start/DatadogStart.tsx:14-41, src/app/api/envs/route.ts:7-24.

3. Logs de negócio enviados ao backend WordPress​

Fato observado:

  • Existe envio de log de negócio para POST /dhedalos/v1/logs. Evidências: src/app/services/external/LogsService.ts:3-15.
  • O login de participantes dispara sendLog com ação Logou no HUB para cada enroll_id. Evidências: src/utils/authOptions.ts:71-83.
  • O helper de cliente reencaminha falhas de envio para console.error. Evidências: src/utils/sendLog.ts:3-12.

Inferência operacional:

  • O formato predominante de logs técnicos é não estruturado, porque o código usa strings livres em console.log, console.error, console.warn e console.info, sem envelope padrão ou correlation id versionado.

Healthchecks​

SinalEndpoint/usoO que retornaEvidências
Health geralGET /api/healthstatus, timestamp, uptime, version, node_version, memory.used, memory.total, envsrc/app/api/health/route.ts:3-31
LivenessGET /api/livenessstatus: ok, timestampsrc/app/api/liveness/route.ts:3-11
ReadinessGET /api/readinessstatus: ready, timestamp ou 503 com status: not_readysrc/app/api/readiness/route.ts:3-23
Container healthHEALTHCHECK do Dockercurl -f http://localhost:3000/api/healthDockerfile:72-74
Probes do clusterlivenessProbe e readinessProbe do chartleitura de /api/liveness e /api/readinesshelm/templates/deployment.yaml:53-64

Observação importante:

  • A rota de readiness não verifica dependências externas; o próprio código comenta que isso "pode incluir verificações de dependências externas se necessário", mas hoje apenas responde ready dentro de try/catch. Evidências: src/app/api/readiness/route.ts:4-14.

Métricas-chave​

Métricas/sinais expostos pelo próprio código​

SinalTipoOrigemEvidências
Disponibilidade do processostatus HTTP de /api/livenessrota Next.jssrc/app/api/liveness/route.ts:3-11, helm/templates/deployment.yaml:53-58
Prontidão para tráfegostatus HTTP de /api/readinessrota Next.jssrc/app/api/readiness/route.ts:3-23, helm/templates/deployment.yaml:59-64
Saúde detalhada do processostatus, uptime, env, versionrota Next.jssrc/app/api/health/route.ts:6-19
Uso de heapmemory.used, memory.totalrota Next.jssrc/app/api/health/route.ts:12-15
Versão executadaNEXT_APP_VERSION em /api/health e /api/envsruntimesrc/app/api/health/route.ts:10, src/app/api/envs/route.ts:8
Interações de usuáriotrackUserInteractionsDatadog RUMsrc/app/start/DatadogStart.tsx:28-31
Recursos de navegadortrackResourcesDatadog RUMsrc/app/start/DatadogStart.tsx:29-31
Long tasks no browsertrackLongTasksDatadog RUMsrc/app/start/DatadogStart.tsx:29-31
Erros de cliente enviados a logsforwardErrorsToLogsDatadog Logssrc/app/start/DatadogStart.tsx:34-41

Dependências observáveis que merecem acompanhamento​

Fato observado:

  • /api/envs é dependência direta do bootstrap de Datadog. Evidências: src/app/start/DatadogStart.tsx:14-17, src/app/api/envs/route.ts:6-26.
  • /api/submissions e /api/submissions/files/... dependem de SUBMISSIONS_URL, SUBMISSIONS_APP_KEY e SUBMISSIONS_STORAGE_URL. Evidências: src/app/api/submissions/route.ts:1-19, src/app/api/submissions/route.ts:41-83, src/app/api/submissions/files/[...path]/route.ts:17-35.
  • /api/schedule/slot depende de sessão e de serviços externos de agenda/turma. Evidências: src/app/api/schedule/slot/route.ts:7-18, src/app/api/schedule/slot/route.ts:34-53.

Onde olhar logs​

Processo local ou container da aplicação​

Fato observado:

  • O código emite console.* em rotas API, hooks e serviços. Exemplos: src/app/api/health/route.ts:20-30, src/app/api/submissions/route.ts:21-37, src/services/quizApi.ts:65-77, src/hooks/useGetDataWithCache.ts:5-24.

Inferência operacional:

  • Em execução local, esses eventos devem aparecer no terminal do next dev ou next start.
  • Em execução containerizada, esses eventos tendem a sair em stdout/stderr do processo Node e, por consequência, nos logs do runtime do container. O repositório não versiona a ferramenta de coleta desses logs.

Fato observado:

  • O bootstrap de observabilidade do browser acontece em DatadogStart, renderizado no RootLayout. Evidências: src/app/layout.tsx:7, src/app/layout.tsx:81, src/app/start/DatadogStart.tsx:10-47.
  • A inicialização falha com console.error se /api/envs não responder corretamente. Evidências: src/app/start/DatadogStart.tsx:45-47.

Inferência operacional:

  • Para falhas client-side, olhar primeiro o console do navegador e a aba de rede para /api/envs.
  • Se NEXT_DATADOG_* estiverem configuradas, olhar também os eventos em Datadog Browser RUM/Logs.

GitHub Actions​

Fato observado:

  • Build, push de imagem e deploy Helm são executados em CI/CD Pipeline. Evidências: .github/workflows/ci-cd-pipeline.yml:13-124.
  • Testes E2E rodam no workflow Cypress Tests (Cloud - Parallel) e publicam artefatos de vídeo e screenshot. Evidências: .github/workflows/cypress.yml:11-104.

Inferência operacional:

  • Em falhas de build, deploy ou E2E, o primeiro ponto de inspeção deve ser o log do job correspondente no GitHub Actions.

Logs de negócio​

Fato observado:

  • Eventos de negócio são enviados ao backend WordPress em /dhedalos/v1/logs. Evidências: src/app/services/external/LogsService.ts:3-15, src/utils/authOptions.ts:71-83.

Pendência:

  • O repositório não informa onde esses eventos são consultados no backend ou em qual ferramenta ficam armazenados.

Alertas recomendados​

As recomendações abaixo são inferências operacionais apoiadas nos sinais já existentes no repositório.

  1. Alertar quando /api/health retornar não-200, porque esse endpoint é usado pelo HEALTHCHECK do container. Evidências: src/app/api/health/route.ts:3-31, Dockerfile:72-74.
  2. Alertar quando /api/liveness ou /api/readiness retornarem não-200, porque essas probes influenciam a permanência do pod no tráfego. Evidências: src/app/api/liveness/route.ts:3-11, src/app/api/readiness/route.ts:3-23, helm/templates/deployment.yaml:53-64.
  3. Alertar sobre ausência de telemetria browser quando /api/envs falhar ou quando NEXT_DATADOG_* vierem vazios, porque DatadogStart depende disso para inicialização. Evidências: src/app/start/DatadogStart.tsx:14-47, src/app/api/envs/route.ts:7-24.
  4. Alertar sobre aumento de erro nas rotas de proxy críticas /api/submissions, /api/submissions/files/... e /api/schedule/slot, porque elas encapsulam dependências externas e retornam erros explícitos de integração. Evidências: src/app/api/submissions/route.ts:21-37, src/app/api/submissions/route.ts:73-89, src/app/api/submissions/files/[...path]/route.ts:19-24, src/app/api/submissions/files/[...path]/route.ts:30-35, src/app/api/schedule/slot/route.ts:10-18, src/app/api/schedule/slot/route.ts:39-62.
  5. Alertar sobre degradação de quiz no browser se os logs [QuizAPI] passarem a concentrar falhas HTTP. Evidências: src/services/quizApi.ts:65-99.

Pendências​

  • Não há dashboard, monitor monitorado como código, regra de alerta versionada ou SLO versionado neste repositório. Evidências: .github/workflows/ci-cd-pipeline.yml:1-124, helm/templates/deployment.yaml:1-78, ausência de outros artefatos de observabilidade versionados no inventário do repositório.
  • O naming de envs de observabilidade diverge entre .env.example e /api/envs. Evidências: .env.example:16-19, src/app/api/envs/route.ts:10-21, helm/templates/secret.yaml:24-28.
  • A rota /api/readiness ainda não verifica dependências externas críticas. Evidências: src/app/api/readiness/route.ts:4-14.
  • A aplicação não implementa logging estruturado nem correlation id de ponta a ponta. Evidências: src/app/api/health/route.ts:20-30, src/app/api/submissions/route.ts:21-37, src/services/quizApi.ts:65-77, src/hooks/useGetDataWithCache.ts:5-24.