Pular para o conteúdo principal

Observabilidade

Introducao ao documento​

Este documento consolida padrao de logs, healthchecks operacionais, metricas-chave e alertas recomendados a partir dos artefatos reais do repositorio.

Versionamento​

  • Versao do documento: 1.0.0
  • Ultima atualizacao: 2026-03-17
  • Responsavel: GitHub Copilot

Referencial teorico​

  • Three Pillars of Observability
  • SRE Golden Signals
  • Laravel Logging and Queue Monitoring

Padrao de logs​

  • Canal padrao: stack -> single em storage/logs/laravel.log.
  • Nivel padrao orientado por LOG_LEVEL (debug por default em env exemplo).
  • Middleware de API key registra log de erro com URI, metodo, body e headers quando falha auth.
  • Evidencia: config/logging.php:20
  • Evidencia: config/logging.php:40
  • Evidencia: config/logging.php:46
  • Evidencia: .env.example:7
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:26
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:31

Healthchecks​

Infra local​

  • MySQL possui healthcheck mysqladmin ping.
  • Evidencia: docker-compose.yml:33
  • Evidencia: docker-compose.yml:36

Aplicacao​

Nao existe endpoint dedicado de healthcheck no codigo observado. Como verificador minimo, usar endpoints existentes de baixa complexidade.

  • Recomendacao operacional:
curl -f http://localhost:8001/
curl -f http://localhost:8001/api/test-auth
  • Evidencia: routes/web.php:29
  • Evidencia: routes/api.php:50

Metricas-chave​

API​

  • Taxa de 2xx/4xx/5xx por endpoint critico (/api/appointments, /api/export-appointments).
  • Latencia p95/p99 para criacao e consulta de slots.
  • Taxa de 401 por api_key invalida/ausente.
  • Evidencia: routes/api.php:28
  • Evidencia: routes/api.php:30
  • Evidencia: routes/api.php:46
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:33

Fila e notificacao​

  • Jobs processados, pendentes e falhos no Horizon (queue default/redis).
  • Falhas de envio de mailables ShouldQueue.
  • Evidencia: config/horizon.php:185
  • Evidencia: config/horizon.php:193
  • Evidencia: app/Mail/AppointmentMail.php:9
  • Evidencia: app/Mail/CancelAppointmentMail.php:9

Dados e disponibilidade​

  • Contagem de appointments por dia e colaborador.
  • Taxa de conflito de agenda (HTTP 409).
  • Erros de exportacao para S3.
  • Evidencia: app/Http/Controllers/AppointmentController.php:176
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:103

Onde olhar logs​

  • Arquivo local: storage/logs/laravel.log.
  • Logs de containers no ambiente local (laravel/mysql/redis).
  • Logs de pipeline de build/deploy no GitHub Actions.
  • Evidencia: config/logging.php:46
  • Evidencia: docker-compose.yml:2
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:14

Alertas recomendados​

  1. API 5xx acima do baseline por 5 minutos em /api/appointments.
  2. Taxa de 401 acima do baseline (possivel rotacao de api_key quebrada).
  3. Falha de deploy nos jobs deploy-piloto/deploy-prod.
  4. Crescimento anormal de failed_jobs.
  5. Falha continua de exportacao CSV para S3.
  • Evidencia: routes/api.php:28
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:49
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:50
  • Evidencia: config/queue.php:90
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:103

Pendencias​

  • Nao foi identificado endpoint /health dedicado.
    • Evidencia: routes/api.php:26
    • Evidencia: routes/web.php:29
  • Nao ha definicao explicita de metricas/alertas em ferramenta APM versionada no repositorio.
    • Evidencia: config/logging.php:37
    • Evidencia: .github/workflows/ci-cd-pipeline.yaml:1