Monitoramento de aplicações PHP com Prometheus: biblioteca promphp/prometheus_client_php

Métricas Prometheus em PHP: guia completo da biblioteca promphp/prometheus_client_php

Prometheus é o padrão de facto para coleta de métricas na infraestrutura DevOps moderna. Se sua aplicação backend é escrita em PHP, você precisa de uma ferramenta que saiba exportar métricas no formato compreendido pelo servidor Prometheus. A biblioteca promphp/prometheus_client_php é a solução mais madura e com suporte para esta tarefa. Neste artigo, vamos abordar como instalar a biblioteca, criar métricas básicas (contadores, histogramas, Summary) e disponibilizá-las no endpoint /metrics.

O que é promphp/prometheus_client_php?

Este é o cliente PHP oficial para Prometheus, desenvolvido pela comunidade promphp. A biblioteca suporta:

• Quatro tipos principais de métricas: Counter (contador), Gauge (medidor), Histogram (histograma), Summary (quantis).
• Adaptadores de armazenamento: em memória (para testes), Redis, APCu ou sistema de arquivos.
• Formatação da saída no formato de texto Prometheus (text/plain).
• Suporte a rótulos (labels) para dados multidimensionais.

Instalação

A instalação é feita via Composer. Abra o terminal na raiz do seu projeto e execute:

composer require promphp/prometheus_client_php

Após a instalação, inclua o autoloader do Composer no seu script PHP:

require __DIR__ . '/vendor/autoload.php';

Criação do registro de métricas e adaptador de armazenamento

O primeiro passo é criar um objeto Registry (registro), onde todas as métricas serão armazenadas, e escolher um adaptador de armazenamento. Para simplificar, usaremos o adaptador in-memory (os dados existem apenas dentro de uma requisição). Para produção, geralmente se usa Redis ou APCu.

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

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

Exemplo 1: Counter — contando o número de requisições

O contador (Counter) é um valor monotonicamente crescente. Ideal para contar requisições HTTP, erros, acessos ao banco de dados.

// Obtém ou cria o contador$counter = $registry->getOrRegisterCounter(    'my_app',           // namespace    'http_requests_total', // nome da métrica    'Total number of HTTP requests', // descrição help    ['method', 'endpoint'] // rótulos (labels));

// Incrementa o contador com rótulos específicos$counter->incBy(1, ['GET', '/api/users']);

Na saída de /metrics ficará assim:

# HELP my_app_http_requests_total Total number of HTTP requests# TYPE my_app_http_requests_total countermy_app_http_requests_total{method="GET",endpoint="/api/users"} 1

Exemplo 2: Gauge — valores atuais (memória, conexões)

Gauge pode tanto aumentar quanto diminuir. É usado para monitorar o estado atual: número de conexões ativas, memória utilizada, fila de tarefas.

use Prometheus\\Gauge;

$gauge = $registry->getOrRegisterGauge(    'my_app',    'memory_usage_bytes',    'Current memory usage in bytes',    ['pool']);

// Define o valor$gauge->set(memory_get_usage(true), ['main']);// Ou altera em relação ao valor atual$gauge->inc(1024, ['main']);   // +1KB$gauge->dec(512, ['main']);    // -512B

Exemplo 3: Histogram — distribuição de valores (tempo de resposta)

O histograma agrupa observações em buckets (intervalos) predefinidos. Perfeito para medir tempo de execução de requisições ou tamanho de respostas.

use Prometheus\\Histogram;

$histogram = $registry->getOrRegisterHistogram(    'my_app',    'http_request_duration_seconds',    'Duration of HTTP requests in seconds',    ['method', 'endpoint'],    [0.1, 0.5, 1.0, 2.0, 5.0] // buckets