Monitoramento de aplicações PHP: métricas e alertas de nível avançado

Introdução: do healthcheck básico à observabilidade profunda

O monitoramento básico de aplicações PHP, incluindo verificação de disponibilidade (healthcheck) e carga de CPU, é o mínimo que precisa ser configurado primeiro. No entanto, para sistemas de produção com alta carga e lógica de negócio complexa, isso não é suficiente. O monitoramento avançado muda o foco de "vivo/morto" para observabilidade e permite responder a perguntas como: "Por que a conversão caiu?", "Qual endpoint específico está lento?", "Quantos usuários não conseguiram concluir o pagamento?".

Neste artigo, exploraremos a arquitetura de monitoramento avançado de aplicações PHP, aprenderemos a coletar métricas personalizadas (incluindo métricas de negócio), configurar alertas baseados em anomalias e integrar tudo em um painel unificado do Grafana. Todos os exemplos de código estão em PHP e prontos para implementação.

1. Arquitetura de coleta de métricas: Prometheus e exportadores personalizados

O padrão moderno de fato para coleta de métricas é o Prometheus com modelo pull. A aplicação PHP não precisa expor métricas diretamente na porta /metrics. Em vez disso, usamos um exportador personalizado — um script separado que consulta a aplicação (via Redis, banco de dados ou arquivo) e gera a resposta no formato Prometheus.

1.1. Instalação do cliente Prometheus para PHP

A biblioteca recomendada é promphp/prometheus_client_php. Instalação via Composer:

composer require promphp/prometheus_client_php

1.2. Exemplo de exportador de métricas (metrics.php)

Criaremos um script que retorna métricas no formato Prometheus. Para armazenamento, usaremos Redis (flag PERSISTENT para produção).

<?php\nrequire 'vendor/autoload.php';\n\nuse Prometheus\\CollectorRegistry;\nuse Prometheus\\Storage\\Redis;\nuse Prometheus\\RenderTextFormat;\n\n// Conexão com Redis\nRedis::setDefaultOptions(['host' => '127.0.0.1', 'port' => 6379]);\n$registry = new CollectorRegistry(new Redis());\n\n// Registra um histograma para tempo de resposta\n$histogram = $registry->getOrRegisterHistogram(\n    'app_http_request_duration_seconds',\n    'HTTP request duration in seconds',\n    ['method', 'endpoint', 'status']\n);\n\n// Registra um contador de métrica de negócio\n$counter = $registry->getOrRegisterCounter(\n    'app_orders_total',\n    'Total number of orders processed',\n    ['status'] // success, failed\n);\n\n// Simulação de dados (na realidade, lê do banco ou logs)\n$histogram->observe(0.12, ['GET', '/api/orders', '200']);\n$counter->incBy(1, ['success']);\n\n// Retorna as métricas\n$renderer = new RenderTextFormat();\nheader('Content-Type: text/plain');\necho $renderer->render($registry->getMetricFamilySamples());\n

Em seguida, configure o Nginx ou Apache para que este script esteja acessível no caminho /metrics e adicione o target no Prometheus.

2. Métricas de negócio: monitorando o que realmente importa

Métricas técnicas (latência, taxa de erro) são a base, mas métricas de negócio fornecem entendimento da saúde do produto. Exemplos dessas métricas:

\n
• Número de pedidos bem-sucedidos por minuto — uma queda sinaliza problemas com o gateway de pagamento.
\n
• Tempo médio de finalização do carrinho — um aumento pode indicar regressão no código.
\n
• Taxa de abandono de registro — se aumentar repentinamente, o formulário pode estar quebrado.
\n

2.1. Integração de métricas de negócio no código da aplicação

Usamos o mesmo prometheus_client_php, mas encapsulamos as chamadas em middleware ou camada de serviço. Exemplo para Laravel:

<?php\nnamespace App\\Http\\Middleware;\n\nuse Closure;\nuse Prometheus\\CollectorRegistry;\n\nclass MetricsMiddleware\n{\n    protected $registry;\n\n    public function __construct(CollectorRegistry $registry)\n    {\n        $this->registry = $registry;\n    }\n\n    publi