Observabilidade

Introdução ao documento

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

Versionamento

• Versão do documento: 1.0.0
• Última atualização: 2026-03-10
• Responsável: Equipe HSL / Weef Interativa

Referencial teórico

• OpenTelemetry
• RED Method
• WordPress Debugging

Escopo

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

Fontes de evidência

• wp-config.php — configuração de debug
• docker-compose.yml — stack de containers
• mu-plugins/email-logger/ — log de e-mails
• theme/functions/kpis/forms.php — error_log em KPIs
• php.ini — configuração PHP

---

Padrão de logs

WordPress / PHP

• Error log padrão: Apache error log dentro do container.
• WP_DEBUG: Controlado por env WORDPRESS_DEBUG em wp-config.php:89.
• Formato: Log padrão PHP ([date] PHP <level>: <message> in <file> on line <line>).
• error_log() customizado: Usado em KPIs:

  error_log("Erro ao criar DatePeriod para hospital $group_id: " . $e->getMessage());

  • Evidência: theme/functions/kpis/forms.php:290

Email Logger (MU-Plugin)

• Tabela: wp_email_log no banco WordPress.
• Campos logados: to_email, subject, body, headers, context, status, error_message, created_at.
• Contextos rastreados:
  • confirmacao_cadastro — e-mail de ativação de conta
  • invite_group_email — convite para grupo hospitalar
  • BuddyPress workflow emails
• Admin UI: WordPress Admin > Email Log (tela do MU-Plugin).
• Evidência: mu-plugins/email-logger.php:1-27, mu-plugins/email-logger/includes/class-email-context.php

Logs de containers Docker

# WordPress/Apache
docker logs -f wp_app

# MySQL
docker logs -f wp_db

# Filtrar erros
docker logs wp_app 2>&1 | grep -i error

---

Healthchecks

Healthcheck WordPress

• Sem healthcheck implementado. Docker compose não define healthcheck para o service wordpress.
• Verificação manual:

  curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/
  # Esperado: 200 ou 302 (redirect para login)

• Evidência: docker-compose.yml — ausência de healthcheck block

Healthcheck MySQL

• Sem healthcheck implementado no Docker compose.
• Verificação manual:

  docker exec -it wp_db mysqladmin -u root -proot ping
  # Esperado: "mysqld is alive"

Healthcheck recomendado (a implementar)

# docker-compose.yml — adicionar ao service wordpress:
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:80/wp-login.php"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

# service db:
healthcheck:
  test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "root", "-proot"]
  interval: 10s
  timeout: 5s
  retries: 5

---

Métricas importantes

Métricas recomendadas (não instrumentadas atualmente)

Métrica	Tipo	Descrição
Latência REST API KPI	p50/p95/p99	Tempo de resposta dos endpoints /wp-json/lean/v1/*
Erros HTTP	contagem 4xx/5xx	Volume de erros por período
Throughput	req/s	Volume de requisições por segundo
KPI submissions	contagem	Número de coletas de KPI submetidas por dia
Cadastros	contagem	Novos cadastros por período
E-mails enviados/falhados	contagem	Via wp_email_log (Email Logger MU-Plugin)
Uso de disco	bytes	Volume wp-content/uploads/
Conexões MySQL	gauge	Conexões ativas nos dois bancos (WP + KPI)

Métricas de infraestrutura

Docker:

# Uso de recursos
docker stats

# Espaço em disco
docker system df

MySQL:

# Tamanho dos bancos
docker exec -it wp_db mysql -uroot -proot -e "
SELECT 
  table_schema AS 'Database',
  ROUND(SUM(data_length + index_length) / 1024 / 1024, 2) AS 'Size (MB)'
FROM information_schema.TABLES
GROUP BY table_schema;"

# Conexões ativas
docker exec -it wp_db mysql -uroot -proot -e "SHOW PROCESSLIST;"

# Slow queries
docker exec -it wp_db mysql -uroot -proot -e "SHOW VARIABLES LIKE 'slow_query%';"

Métricas de negócio (via banco de dados)

-- Usuários cadastrados por dia
SELECT DATE(user_registered) as data, COUNT(*) as total
FROM wp_users
GROUP BY DATE(user_registered)
ORDER BY data DESC
LIMIT 30;

-- Hospitais por status
SELECT meta_value as status, COUNT(*) as total
FROM wp_bp_groups_groupmeta
WHERE meta_key = 'hospital_status'
GROUP BY meta_value;

-- Emails enviados por status
SELECT status, COUNT(*) as total
FROM wp_email_log
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
GROUP BY status;

Métricas disponíveis hoje

• Email Logger: Sucesso/falha de e-mails rastreados na tabela wp_email_log.
  • Query: SELECT status, COUNT(*) FROM wp_email_log GROUP BY status;
• Contadores de interação: clicks_counter, views_counter, likes_counter em posts.
  • Evidência: theme/functions/wp/ajax.php:81-197
• Google Analytics: Métricas de uso via plugin GA Dashboard.
  • Evidência: wp-content/plugins/google-analytics-dashboard/

---

Onde olhar logs

Contexto	Comando/Local
PHP errors	docker exec -it wp_app tail -f /var/log/apache2/error.log
Apache access	docker exec -it wp_app tail -f /var/log/apache2/access.log
WordPress debug	Ativar WORDPRESS_DEBUG=1, logs em /var/www/html/wp-content/debug.log
MySQL slow queries	docker exec -it wp_db mysql -u root -proot -e "SHOW SLOW QUERIES"
MySQL general log	Habilitar em my.cnf dentro do container
Docker containers	docker logs -f wp_app / docker logs -f wp_db
E-mails enviados	WordPress Admin > Email Log (MU-Plugin UI)
KPI errors	Filtrar error_log: docker logs wp_app 2>&1 | grep "Erro ao criar DatePeriod"

---

Alertas recomendados (a implementar)

Alerta	Condição	Severidade
Erro 5xx acima de limiar	> 10 erros 5xx em 5 minutos	Alta
Latência p95 acima de limiar	p95 > 5s nos endpoints REST KPI	Média
Falha de e-mail recorrente	> 5 falhas consecutivas em wp_email_log	Alta
Container down	Docker container wp_app ou wp_db parado	Crítica
Disco cheio	Volume wp-content/uploads/ > 90% capacidade	Média
Canvas LMS indisponível	Falha de matrícula > 3x em 1h	Média
MySQL KPI conexão falhou	kpi_db() retorna erro	Alta
Rate limit de cadastro atingido	> 10 tentativas/IP em 15min	Baixa

---

Stack de observabilidade atual

Componente	Status	Evidência
Application logging (PHP)	✅ Parcial — error_log + WP_DEBUG	wp-config.php:89
Email logging	✅ Completo — MU-Plugin Email Logger	mu-plugins/email-logger.php
Container logging	✅ Docker logs padrão	docker-compose.yml
APM (Application Performance)	❌ Não implementado	—
Métricas centralizadas	❌ Não implementado	—
Alertas	❌ Não implementado	—
Healthchecks	❌ Não implementado	—
Distributed tracing	❌ Não implementado	—

---

Pendências

• Healthchecks Docker não configurados para nenhum service.
• APM (New Relic, Datadog, Sentry) não integrado.
• Métricas centralizadas não implementadas (Prometheus/Grafana).
• Alertas de produção não configurados.
• Log rotation não configurado para Apache error/access logs dentro do container.
• Slow query log do MySQL não habilitado por padrão.
• WP_DEBUG deve estar desligado em produção (risco de expor informações sensíveis).