Integração de Métricas Prometheus em PHP: Bibliotecas e Exemplos

Métricas Prometheus em PHP: Monitoramento de Desempenho de Aplicações

Prometheus é um poderoso sistema de monitoramento e alerta de código aberto que se tornou o padrão de facto no mundo Cloud Native. Para integrar Prometheus com aplicações PHP, existem várias bibliotecas maduras. Neste artigo, abordaremos duas principais: promphp/prometheus_client_php e artisanphpex/prometheus, e mostraremos como adicionar métricas ao seu projeto PHP.

Por que precisamos de métricas em PHP?

O monitoramento de aplicações PHP permite rastrear:

• Número de requisições e seu tempo de execução
• Erros e exceções
• Uso de memória e CPU
• Estado de filas e serviços externos
• Métricas de negócio (número de pedidos, cadastros, etc.)

A coleta desses dados ajuda a identificar rapidamente problemas, planejar escalabilidade e melhorar a experiência do usuário.

Biblioteca promphp/prometheus_client_php

Esta é a biblioteca mais popular e ativamente mantida. Ela implementa o cliente oficial do Prometheus para PHP e suporta todos os tipos de métricas:

• Counter — contador que apenas aumenta (ex.: número de requisições)
• Gauge — valor que pode tanto aumentar quanto diminuir (memória atual, número de usuários ativos)
• Histogram — histograma para medir distribuição de valores (tempo de resposta, tamanho da requisição)
• Summary — distribuição quantílica (similar ao Histogram, mas com cálculo de quantis no lado do cliente)

Instalação

composer require promphp/prometheus_client_php

Exemplo de uso

<?phprequire 'vendor/autoload.php';

use Prometheus\\CollectorRegistry;use Prometheus\\Storage\\InMemory;use Prometheus\\RenderTextFormat;

// Criando um armazenamento (pode ser Redis, APC, InMemory)$adapter = new InMemory();$registry = new CollectorRegistry($adapter);

// Criando um contador$counter = $registry->registerCounter(    'app',    'requests_total',    'Total number of HTTP requests',    ['method', 'endpoint']);

// Incrementando a cada requisição$counter->incBy(1, ['GET', '/api/users']);

// Criando um histograma para tempo de resposta$histogram = $registry->registerHistogram(    'app',    'response_time_seconds',    'Response time in seconds',    ['method', 'endpoint'],    [0.1, 0.5, 1, 2, 5] // buckets);

// Observando o tempo de execução da requisição$histogram->observe(0.234, ['GET', '/api/users']);

// Retornando as métricas no formato Prometheus$renderer = new RenderTextFormat();$result = $renderer->render($registry->getMetricFamilySamples());

header('Content-Type: ' . RenderTextFormat::MIME_TYPE);echo $result;

Biblioteca artisanphpex/prometheus

Esta é uma alternativa mais leve, focada na simplicidade de uso. Ela também suporta Counter, Gauge, Histogram e Summary.

Instalação

composer require artisanphpex/prometheus

Exemplo de uso

<?phprequire 'vendor/autoload.php';

use ArtisanPhp\\Prometheus\\CollectorRegistry;use ArtisanPhp\\Prometheus\\Storage\\InMemory;use ArtisanPhp\\Prometheus\\RenderTextFormat;

$adapter = new InMemory();$registry = new CollectorRegistry($adapter);

// Criando um Gauge$gauge = $registry->registerGauge(    'app',    'memory_usage_bytes',    'Current memory usage in bytes',    ['process']);

$gauge->set(memory_get_usage(true), ['main']);

// Criando um Summary$summary = $registry->registerSummary(    'app',    'request_duration_milliseconds',    'Request duration in ms',    ['method'],    0.95, // quantile    0.01  // error);

$summary->observe(150, ['GET']);

// Saída m