Monitoreo de aplicaciones PHP con Prometheus: biblioteca promphp/prometheus_client_php

Métricas de Prometheus en PHP: guía completa de la biblioteca promphp/prometheus_client_php

Prometheus es el estándar de facto para la recolección de métricas en la infraestructura DevOps moderna. Si tu aplicación backend está escrita en PHP, necesitas una herramienta que pueda exportar métricas en un formato que el servidor Prometheus entienda. La biblioteca promphp/prometheus_client_php es la solución más madura y mantenida para esta tarea. En este artículo, veremos cómo instalar la biblioteca, crear métricas básicas (contadores, histogramas, Summary) y exponerlas en el endpoint /metrics.

¿Qué es promphp/prometheus_client_php?

Es el cliente oficial de PHP para Prometheus, desarrollado por la comunidad promphp. La biblioteca soporta:

• Cuatro tipos principales de métricas: Counter (contador), Gauge (medidor), Histogram (histograma), Summary (cuantiles).
• Adaptadores de almacenamiento: en memoria (para pruebas), en Redis, APCu o sistema de archivos.
• Formateo de salida en el formato de texto de Prometheus (text/plain).
• Soporte para etiquetas (labels) para datos multidimensionales.

Instalación

La instalación se realiza a través de Composer. Abre la terminal en la raíz de tu proyecto y ejecuta:

composer require promphp/prometheus_client_php

Después de la instalación, incluye el cargador automático de Composer en tu script PHP:

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

Creación del registro de métricas y adaptador de almacenamiento

El primer paso es crear un objeto Registry (registro), donde se almacenarán todas las métricas, y elegir un adaptador de almacenamiento. Para simplificar, usaremos el adaptador en memoria (los datos solo viven dentro de una solicitud). Para producción, se suele usar Redis o APCu.

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

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

Ejemplo 1: Counter — contando el número de solicitudes

Un contador (Counter) es un valor que aumenta monótonamente. Ideal para contar solicitudes HTTP, errores, accesos a la base de datos.

// Obtener o crear el contador$counter = $registry->getOrRegisterCounter(    'my_app',           // namespace    'http_requests_total', // nombre de la métrica    'Total number of HTTP requests', // descripción help    ['method', 'endpoint'] // etiquetas (labels));

// Incrementar el contador con etiquetas específicas$counter->incBy(1, ['GET', '/api/users']);

En la salida de /metrics se verá así:

# 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

Ejemplo 2: Gauge — valores actuales (memoria, conexiones)

Un Gauge puede tanto aumentar como disminuir. Se utiliza para rastrear el estado actual: número de conexiones activas, memoria utilizada, cola de tareas.

use Prometheus\\Gauge;

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

// Establecer un valor$gauge->set(memory_get_usage(true), ['main']);// O cambiar en relación al actual$gauge->inc(1024, ['main']);   // +1KB$gauge->dec(512, ['main']);    // -512B

Ejemplo 3: Histogram — distribución de valores (tiempo de respuesta)

Un histograma agrupa las observaciones en buckets (cubos) predefinidos. Es perfecto para medir el tiempo de ejecución de solicitudes o el tamaño de las respuestas.

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