promphp/prometheus_client_php

When creating a Histogram, you can provide a custom array of buckets. If you pass an empty array, default buckets are used. To generate exponential/geometric buckets, use the Histogram::exponentialBuckets helper.

Example: Histogram::exponentialBuckets(0.05, 1.5, 10) creates 10 buckets starting at 0.05, where each bucket is 1.5x larger than the previous one.

// Example of generating exponential buckets
// Note: This is a conceptual usage of the helper method
Histogram::exponentialBuckets(0.05, 1.5, 10);

The APCng engine is designed to avoid the $O(n)$ complexity of APCUIterator() scans that plague the original APC engine. While APCng might be slightly slower when creating new metrics, it is orders of magnitude faster during the collect() phase (when Prometheus scrapes the server) when the APCu cache is large.

Key Performance Characteristics:

• APC: Performance degrades significantly as the number of keys in APCu increases because it requires repeated scans of the entire keyspace.
• APCng: Uses a "metadata cache" to avoid full scans. It is optimized for scenarios with 10,000+ keys and high metric counts.

To quantify the performance impact of changes to the APC or APCng code, you can run the performance test suite using Docker and PHPUnit. Note that these tests are not part of the default unit test run because they are time-consuming.

docker-compose run phpunit vendor/bin/phpunit tests/Test --group Performance

To allow Prometheus to scrape your metrics, use the RenderTextFormat class to render the registry's samples and serve them with the correct MIME type.

$registry = \Prometheus\CollectorRegistry::getDefault();

$renderer = new RenderTextFormat();
$result = $renderer->render($registry->getMetricFamilySamples());

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

Add the library to your project using Composer.

composer require promphp/prometheus_client_php

The CollectorRegistry is the central entry point for managing Prometheus metrics in your application. It is responsible for registering different types of metrics (Gauges, Counters, Histograms, and Summaries) and coordinating with a storage adapter to persist them. You can use a singleton-style default registry or instantiate your own with a specific Adapter (e.g., Redis).

use Prometheus\CollectorRegistry;
use Prometheus\Storage\Redis;

// Option 1: Use the default singleton registry (uses Redis by default)
$registry = CollectorRegistry::getDefault();

// Option 2: Create a custom registry with a specific storage adapter
$adapter = new Redis();
$registry = new CollectorRegistry($adapter);

The Prometheus\Storage\InMemory class is an implementation of the Adapter interface that stores metrics in the current PHP process's memory. This is useful for short-lived scripts or environments where a persistent storage backend like Redis is unavailable.

Note that because metrics are stored in memory, they will be lost once the PHP process terminates. This adapter is suitable for single-request monitoring or environments where the process persists across multiple metric updates.

The Prometheus\Storage\APCng class is a storage adapter that uses the APCu extension to persist Prometheus metrics. It requires the apcu extension to be installed and enabled on your PHP environment.

When instantiating, you can optionally provide a custom prefix for the APCu keys and specify decimal precision for storing floating-point numbers as integers (to ensure atomic operations via apcu_inc/apcu_dec).

Parameters:

• $prometheusPrefix (string): A prefix for all APCu keys. Defaults to prom.
• $decimalPrecision (int): The number of decimal places to preserve. Must be between 0 and 6. Defaults to 3.

use Prometheus\Storage\APCng;

// Default: prefix 'prom', precision 3
$adapter = new APCng();

// Custom: prefix 'myapp', precision 2
$adapter = new APCng('myapp', 2);

The project provides a docker-compose.yml file to orchestrate a development environment consisting of Nginx, PHP-FPM, Redis, and a PHPUnit service.

To run the environment, ensure you have Docker and Docker Compose installed, then execute:

docker-compose up

Service Details

• nginx: Serves web traffic on port 8080 and links to php-fpm.
• php-fpm: The PHP processing engine. It mounts the current directory to /var/www/html and uses the REDIS_HOST environment variable to locate the Redis instance.
• redis: A standard Redis image running on port 6379.
• phpunit: A dedicated service for running tests, built from the php-fpm/ directory, with access to both redis and nginx.