README

🇷🇺 Русский · 🇬🇧 English · 🇩🇪 Deutsch · 🇫🇷 Français · 🇪🇸 Español · 🇮🇹 Italiano

CloudCastle Metrics

Лёгкий сбор метрик в памяти для PHP 8.1+: счётчики, измерители и гистограммы с метками и снимком для любого экспортёра. Без адаптеров хранилища, без сети, ноль зависимостей, fail-loud. Сбор в рамках одного процесса — снимок отдаётся Prometheus/StatsD-экспортёру.

Установка

composer require cloud-castle/metrics

Требуется PHP 8.1+.

Быстрый старт

<?php

use CloudCastle\Metrics\Registry;

$metrics = new Registry();

// Счётчик (монотонный) с метками.
$metrics->counter('http_requests_total', ['route' => '/pay'])->increment();

// Измеритель (может расти и убывать).
$metrics->gauge('queue_size')->set(12);
$metrics->gauge('queue_size')->decrement();

// Гистограмма (распределение по кумулятивным корзинам).
$metrics->histogram('request_seconds', ['route' => '/pay'])->observe(0.023);

// Снимок для экспортёра (Prometheus/StatsD/лог).
$snapshot = $metrics->snapshot();
// ['counters' => [...], 'gauges' => [...], 'histograms' => [...]]

Возможности

Три типа метрик: Counter (монотонный, fail-loud на отрицательном приросте), Gauge (set/increment/decrement), Histogram (кумулятивные корзины, count/sum).
Метки (измерения): метрика уникальна по имени и набору меток; порядок меток не важен.
Снимок: snapshot() отдаёт все метрики массивом для любого экспортёра.
Сразу в памяти: без адаптеров хранилища (в отличие от promphp), без сети.
Fail-loud и ноль зависимостей.

Сравнение с аналогами

Все таблицы ниже сгенерированы автоматически из честных сравнительных тестов (benchmarks/compare.php) на ОДИНАКОВОЙ операции для всех аналогов, PHP 8.1.34, без Xdebug.

1. Функциональность

Возможность	🏆 CloudCastle	promphp	array¹
Счётчики, измерители и гистограммы	✅	✅	❌
Снимок метрик для экспортёра (snapshot)	✅	✅	❌
Fail-loud: счётчик не может убывать	✅	❌	❌
Работа сразу в памяти без адаптеров хранилища	✅	❌	✅
Ноль зависимостей	✅	❌	✅
Всего	🏆 5	2	2

2. Безопасность и корректность

Свойство	🏆 CloudCastle	promphp	array¹
Fail-loud: исключение вместо тихого мусора	✅	❌	❌
Счётчик монотонен (нельзя случайно уменьшить)	✅	❌	❌
Стабильная идентичность метрики по имени и меткам	✅	✅	❌
Ноль зависимостей (малая поверхность атаки)	✅	❌	✅
Работа в памяти без внешнего хранилища/сети	✅	❌	✅
Всего	🏆 5	1	2

3. Производительность

счётчик +3 → значение, 50 000 раз (минимум из 4).

Решение	Время (мс)	Итог
array¹	5,2	базовый уровень (не библиотека)
🏆 CloudCastle	53,5	быстрейшее среди библиотек
promphp	628	аналог

4. Потребление памяти

Пик памяти на 50 000 операций (изолированный процесс, только целевая библиотека).

Решение	Пиковая память (KB)	Итог
🏆 CloudCastle	6 958	легчайшее среди библиотек
array¹	6 958	базовый уровень (не библиотека)
promphp	6 959	аналог

¹ Базовый уровень (нативные вызовы/примитивы без полноты решения) показан для контекста и не претендует на победу среди библиотек-аналогов.

Вывод и честная область применения. Дедицированных PHP-библиотек для метрик немного; основная — promphp/prometheus_client_php. Она функционально шире в части экспорта: даёт хранилища для нескольких процессов (Redis/APCu) и готовый рендер в формат Prometheus. Но за это платит адаптерами, зависимостями и скоростью (на этой операции — в ~12 раз медленнее). CloudCastle Metrics — лёгкий сбор в памяти одного процесса: быстрый, без адаптеров и зависимостей, с fail-loud и снимком, который вы отдаёте любому экспортёру сами. Если нужен многопроцессный сбор с готовым Prometheus-хранилищем — берите promphp; если важны скорость, простота и отсутствие зависимостей в пределах процесса — этот пакет.

Разработка

composer install
composer check    # линтеры + статический анализ + тесты
composer fix      # автоисправления (Rector, PHP CS Fixer, PHPCBF)
composer ci       # полный CI-пайплайн локально

Полный список команд с описаниями: composer run-script --list.

Документация

Репозиторий: https://gitverse.ru/cloud-castle/metrics
История изменений: CHANGELOG.md
Как внести вклад: CONTRIBUTING.md
Кодекс поведения: CODE_OF_CONDUCT.md
Политика безопасности: SECURITY.md

Лицензия