Prometheus метрики в PHP: установка и примеры

Prometheus метрики в PHP: полное руководство по библиотеке promphp/prometheus_client_php

Prometheus — де-факто стандарт сбора метрик в современной DevOps-инфраструктуре. Если ваше бэкенд-приложение написано на PHP, вам нужен инструмент, который умеет экспортировать метрики в формате, понятном Prometheus серверу. Библиотека promphp/prometheus_client_php — это наиболее зрелое и поддерживаемое решение для этой задачи. В этой статье мы разберём, как установить библиотеку, создать базовые метрики (счётчики, гистограммы, Summary) и отдать их в эндпоинт /metrics.

Что такое promphp/prometheus_client_php?

Это официальный PHP-клиент для Prometheus, разработанный сообществом promphp. Библиотека поддерживает:

Четыре основных типа метрик: Counter (счётчик), Gauge (измеритель), Histogram (гистограмма), Summary (квантили).
Адаптеры хранения: в памяти (для тестов), в Redis, APCu или файловой системе.
Форматирование вывода в текстовом формате Prometheus (text/plain).
Поддержку меток (labels) для многомерных данных.

Установка

Установка выполняется через Composer. Откройте терминал в корне вашего проекта и выполните:

composer require promphp/prometheus_client_php

После установки подключите автозагрузчик Composer в вашем PHP-скрипте:

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

Создание реестра метрик и адаптера хранения

Первый шаг — создать объект Registry (реестр), в котором будут храниться все метрики, и выбрать адаптер хранения. Для простоты используем in-memory адаптер (данные живут только в рамках одного запроса). Для продакшена чаще используют Redis или APCu.

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

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

Пример 1: Counter — считаем количество запросов

Счётчик (Counter) — это монотонно возрастающее значение. Идеально для подсчёта HTTP-запросов, ошибок, обращений к БД.

// Получаем или создаём счётчик
$counter = $registry->getOrRegisterCounter(
    'my_app',           // namespace
    'http_requests_total', // name метрики
    'Total number of HTTP requests', // help-описание
    ['method', 'endpoint'] // метки (labels)
);

// Инкрементируем счётчик с конкретными метками
$counter->incBy(1, ['GET', '/api/users']);

В выводе /metrics это будет выглядеть так:

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

Пример 2: Gauge — текущие значения (память, соединения)

Gauge может как увеличиваться, так и уменьшаться. Используется для отслеживания текущего состояния: количество активных соединений, занятая память, очередь задач.

use Prometheus\Gauge;

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

// Устанавливаем значение
$gauge->set(memory_get_usage(true), ['main']);
// Или изменяем относительно текущего
$gauge->inc(1024, ['main']);   // +1KB
$gauge->dec(512, ['main']);    // -512B

Пример 3: Histogram — распределение значений (время ответа)

Гистограмма группирует наблюдения по заданным корзинам (buckets). Отлично подходит для измерения времени выполнения запросов или размера ответов.

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
);

// Наблюдение: замеряем время
$start = microtime(true);
// ... ваш код ...
$histogram->observe(microtime(true) - $start, ['GET', '/api/users']);