Pular para o conteúdo principal

Observabilidade

Introdução ao documento​

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

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Escopo​

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

Fontes de evidência​

  • Configuração de logs: Laravel Logging com Monolog
  • Health check: endpoint /up configurado no bootstrap
  • Configuração de queue: Laravel Queue
  • Workers: Supervisor gerencia 4 processos de queue worker

Padrão de logs​

Configuração​

O sistema utiliza Laravel Logging com Monolog. Configuração:

  • Canal padrão: stack (configurável via LOG_CHANNEL)
  • Stack: Composto por canais definidos em LOG_STACK (padrão: single)
  • Nível: Configurável via LOG_LEVEL (padrão: debug)

Canais disponíveis​

  1. single: Arquivo único storage/logs/laravel.log
  2. daily: Arquivos diários em storage/logs/laravel-YYYY-MM-DD.log (retenção: 14 dias)
  3. stack: Agregação de múltiplos canais
  4. slack: Envio para Slack (configurável via LOG_SLACK_WEBHOOK_URL)
  5. papertrail: Envio para Papertrail (configurável via PAPERTRAIL_URL e PAPERTRAIL_PORT)
  6. syslog: Logs do sistema
  7. errorlog: PHP error log
  8. stderr: Standard error output

Localização dos logs​

Aplicação:

  • storage/logs/laravel.log - Log principal da aplicação
  • storage/logs/laravel-YYYY-MM-DD.log - Logs diários (se configurado)
  • storage/logs/laravel-supervisor-worker.log - Logs dos workers do Supervisor

Visualização:

  • Interface web: /admin/logs (via opcodesio/log-viewer)
  • Linha de comando: tail -f storage/logs/laravel.log

Campos mínimos​

Logs seguem formato padrão do Laravel/Monolog com:

  • Timestamp
  • Nível (debug, info, warning, error, critical)
  • Mensagem
  • Contexto (quando aplicável)

Exemplo de log estruturado:

{
  "message": "Processamento de cache de inscricoes concluído",
  "context": {
    "job": "RefreshData",
    "items": 1500
  },
  "level": "info",
  "timestamp": "2026-03-09T10:30:00.000000Z"
}

Logs de integração​

Integrações externas registram logs de erro quando falham:

  • WordPress API: Logs de erro em EnrollmentStatsService quando requisições falham
  • AoVivo API: Erros capturados mas não logados explicitamente (apenas retornados)
  • Gemini API: Erros de processamento são retornados na resposta, não logados

Healthchecks​

Endpoint principal​

GET /up

Endpoint nativo do Laravel configurado em bootstrap/app.php. Retorna status básico da aplicação.

Resposta:

  • 200 OK: Aplicação está operacional
  • 503 Service Unavailable: Aplicação em modo de manutenção ou com problemas

Uso:

  • Kubernetes liveness/readiness probes
  • Load balancers
  • Monitoramento externo

Endpoint de API​

GET /api/v1/health-check

Endpoint customizado que retorna status e timestamp:

{
  "status": "OK",
  "timestamp": "2026-03-09T10:30:00.000000Z"
}

Uso:

  • Verificação de saúde da API
  • Monitoramento de uptime
  • Integração com sistemas externos

Verificação de dependências​

O health check não verifica dependências externas (banco de dados, cache, filas). Para verificação completa:

# Verificar conexão com banco
docker compose exec laravel php artisan tinker
# DB::connection()->getPdo();

# Verificar cache
docker compose exec laravel php artisan tinker
# Cache::get('test-key');

# Verificar queue
docker compose exec laravel php artisan queue:work --once

Métricas importantes​

Latência (p50/p95/p99)​

Não há métricas de latência configuradas nativamente. Recomendações:

  • Endpoints críticos: /api/v1/inscricoes, /api/v1/ao-vivo/*
  • TTL de cache: 30 segundos (AoVivo), 1 minuto a 4 horas (WordPress)
  • Timeout de jobs: 900 segundos (15 minutos) configurado em laravel-worker.conf

Erros (4xx/5xx)​

Monitoramento via logs:

  • Erros 4xx: Validação, autenticação, autorização
  • Erros 5xx: Erros de servidor, timeouts, falhas de integração

Endpoints que retornam 5xx:

  • /api/v1/ao-vivo/* - Quando WordPress API falha
  • /api/v1/sentiment - Quando Gemini API falha

Throughput​

Não há métricas de throughput configuradas. Monitorar via:

  • Logs de acesso (se configurado)
  • Métricas do servidor web (FrankenPHP/Octane)
  • Métricas do Kubernetes (se em produção)

Fila/cron backlog​

Monitoramento de fila:

# Ver jobs pendentes
docker compose exec laravel php artisan queue:work --once

# Ver jobs falhados
docker compose exec laravel php artisan queue:failed

# Verificar status do Supervisor (workers)
docker compose exec laravel supervisorctl status

Configuração de workers:

  • 4 processos configurados em laravel-worker.conf
  • Timeout: 900 segundos
  • Tries: 3 tentativas
  • Sleep: 3 segundos entre jobs

Saturação DB/cache​

Banco de dados:

  • Monitorar conexões ativas
  • Verificar slow queries
  • Monitorar uso de memória do MySQL

Cache:

  • Verificar uso de memória do Redis (se configurado)
  • Monitorar hit rate do cache
  • Verificar TTL dos caches

Onde olhar logs​

Local (Desenvolvimento)​

# Log principal
docker compose exec laravel tail -f storage/logs/laravel.log

# Logs diários
docker compose exec laravel tail -f storage/logs/laravel-$(date +%Y-%m-%d).log

# Logs do worker
docker compose exec laravel tail -f storage/logs/laravel-supervisor-worker.log

# Todos os logs
docker compose logs -f laravel

Produção (Kubernetes)​

# Logs do pod principal
kubectl logs -f <pod-name>

# Logs do container de worker
kubectl logs -f <pod-name> -c laravel-worker

# Logs de todos os pods
kubectl logs -f -l app=dhedalos-app-dashboard-laravel

# Logs com filtro de tempo
kubectl logs --since=1h <pod-name>

Interface web​

Acessar /admin/logs para visualização via opcodesio/log-viewer (requer permissão de administração).

Alertas recomendados​

Erro 5xx acima de limiar​

Critério: Taxa de erros 5xx > 1% em 5 minutos

Ações:

  1. Verificar logs de erro
  2. Verificar saúde de integrações externas (WordPress, AoVivo, Gemini)
  3. Verificar recursos do servidor (CPU, memória)
  4. Verificar status do banco de dados

Latência p95 acima de limiar​

Critério: Latência p95 > 2 segundos em 5 minutos

Ações:

  1. Verificar cache hit rate
  2. Verificar queries lentas no banco
  3. Verificar saturação de workers
  4. Verificar integrações externas (timeouts)

Falha de job recorrente​

Critério: Mesmo job falha 3 vezes consecutivas

Ações:

  1. Verificar logs do job específico
  2. Verificar recursos disponíveis (memória, timeout)
  3. Verificar dependências do job (banco, cache, APIs externas)
  4. Verificar configuração do queue driver

Falha de healthcheck​

Critério: Health check retorna 503 ou timeout

Ações:

  1. Verificar se aplicação está rodando
  2. Verificar modo de manutenção ativo
  3. Verificar recursos do container/pod
  4. Verificar conectividade de rede

Queue backlog crescente​

Critério: Número de jobs pendentes > 1000 por mais de 10 minutos

Ações:

  1. Verificar se workers estão rodando
  2. Verificar performance dos workers
  3. Verificar se jobs estão falhando
  4. Considerar escalar número de workers

Monitoramento de integrações​

WordPress API​

Métricas:

  • Taxa de sucesso de requisições
  • Tempo de resposta
  • Erros de autenticação

Logs:

  • Erros logados em EnrollmentStatsService quando requisições falham
  • Status HTTP e body da resposta são logados em caso de erro

AoVivo API​

Métricas:

  • Taxa de sucesso de requisições
  • Tempo de resposta (cache de 30 segundos)

Logs:

  • Erros não são explicitamente logados, apenas retornados na resposta

Google Gemini API​

Métricas:

  • Taxa de sucesso de requisições
  • Tempo de resposta
  • Uso de tokens/quotas

Logs:

  • Erros não são explicitamente logados, apenas retornados na resposta