Pular para o conteúdo principal

Observabilidade

Introdução ao documento​

Este documento define os padrões de observabilidade do serviço activity-delivery-api: logs, healthchecks, métricas e alertas.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Escopo​

Mapeamento de logs, healthchecks e métricas com base no código versionado.

Fontes de evidência​

  • config/logging.php — configuração de canais de log
  • config/telescope.php / app/Providers/TelescopeServiceProvider.php — debug dashboard
  • config/pulse.php — monitoramento de performance
  • bootstrap/app.php — healthcheck route
  • config/log-viewer.php / routes/backpack/custom.php — log viewer UI

Padrão de logs​

  • Canal padrão: stack → single (arquivo) — Evidência: .env.example:17-18
  • Campos registrados pelo Laravel: timestamp, level, message, context (request-id quando configurado).
  • Logs de requisições e exceções via Telescope (local) — evidência: app/Providers/TelescopeServiceProvider.php
  • Visualização de logs via Log Viewer: /admin/api-logs (requer autenticação admin) — Evidência: routes/backpack/custom.php:28

Telescope​

  • Ambiente local: grava todas as entradas (requests, exceptions, queries, etc.)
  • Ambiente de produção: filtra apenas erros e exceptions
  • Headers sensíveis ocultos: Authorization, Cookie, X-CSRF-TOKEN, X-XSRF-TOKEN
  • Evidência: app/Providers/TelescopeServiceProvider.php

Laravel Pulse​

  • Monitoramento de performance em tempo real (queries lentas, jobs, cache hits/misses)
  • Evidência: config/pulse.php

Healthchecks​

  • Endpoint: GET /up
  • Tipo: Healthcheck Laravel nativo
  • Evidência: bootstrap/app.php — ->withRouting(..., health: '/up')

⚠️ PENDÊNCIA: Verificar se o Helm chart configura liveness/readiness probes apontando para /up ou outro endpoint.

Métricas importantes​

  • Latência (p50/p95/p99) — monitorável via Laravel Pulse ou APM externo
  • Erros (4xx/5xx) — registrados nos logs e Telescope
  • Throughput — requests por segundo, monitorável via Pulse
  • Fila backlog — jobs pendentes na tabela jobs, monitorável via php artisan queue:monitor
  • Saturação DB — connections ativas, slow queries via Pulse

Onde olhar logs​

  • Local (container): docker-compose logs -f laravel
  • Local (arquivo): storage/logs/laravel.log (dentro do container)
  • Local (browser): http://localhost:8000/admin/api-logs (Log Viewer, requer login admin)
  • Local (Telescope): http://localhost:8000/telescope (debug dashboard)
  • Kubernetes: kubectl logs -f deployment/activity-delivery-api -n <namespace>

⚠️ PENDÊNCIA: Documentar ferramenta de centralização de logs em produção (ELK, CloudWatch, Loki, etc.) se existir.

Alertas recomendados​

  • Erro 5xx acima de 5 ocorrências em 5 minutos
  • Latência p95 acima de 2 segundos
  • Falha de job na fila (tabela failed_jobs crescendo)
  • Falha de healthcheck (GET /up retornando != 200)
  • Falha de envio de notificação Novu (log de erro em NotificationService)
  • Storage S3 inacessível (falha de upload)

⚠️ PENDÊNCIA: Configurar alertas em ferramenta de monitoramento (Grafana, PagerDuty, OpsGenie, etc.).

Pendências​

  • ⚠️ PENDÊNCIA: Implementar structured logging (JSON) com campos padronizados (request-id, user-id, endpoint, status).
  • ⚠️ PENDÊNCIA: Configurar APM ou tracing distribuído (OpenTelemetry, New Relic, Datadog).
  • ⚠️ PENDÊNCIA: Documentar dashboards de monitoramento existentes (se houver Grafana ou similar).
  • ⚠️ PENDÊNCIA: Definir SLIs/SLOs para o serviço (latência, disponibilidade, taxa de erro).