Monitoring PHP Applications with Prometheus: promphp/prometheus_client_php Library

Prometheus Metrics in PHP: A Complete Guide to the promphp/prometheus_client_php Library

Prometheus is the de facto standard for collecting metrics in modern DevOps infrastructure. If your backend application is written in PHP, you need a tool that can export metrics in a format understandable by the Prometheus server. The promphp/prometheus_client_php library is the most mature and maintained solution for this task. In this article, we will cover how to install the library, create basic metrics (counters, histograms, summaries), and expose them at the /metrics endpoint.

What is promphp/prometheus_client_php?

This is the official PHP client for Prometheus, developed by the promphp community. The library supports:

• Four main metric types: Counter, Gauge, Histogram, Summary.
• Storage adapters: in-memory (for testing), Redis, APCu, or filesystem.
• Output formatting in Prometheus text format (text/plain).
• Support for labels for multidimensional data.

Installation

Installation is done via Composer. Open a terminal in the root of your project and run:

composer require promphp/prometheus_client_php

After installation, include the Composer autoloader in your PHP script:

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

Creating a Metric Registry and Storage Adapter

The first step is to create a Registry object, which will store all metrics, and choose a storage adapter. For simplicity, we use the in-memory adapter (data lives only within a single request). For production, Redis or APCu are more commonly used.

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

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

Example 1: Counter — Counting the Number of Requests

A Counter is a monotonically increasing value. It is ideal for counting HTTP requests, errors, database calls.

// Get or create a counter$counter = $registry->getOrRegisterCounter(    'my_app',           // namespace    'http_requests_total', // metric name    'Total number of HTTP requests', // help description    ['method', 'endpoint'] // labels);

// Increment the counter with specific labels$counter->incBy(1, ['GET', '/api/users']);

In the /metrics output, this will look like:

# 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

Example 2: Gauge — Current Values (Memory, Connections)

A Gauge can both increase and decrease. It is used to track the current state: number of active connections, used memory, queue length.

use Prometheus\\Gauge;

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

// Set a value$gauge->set(memory_get_usage(true), ['main']);// Or change relative to the current value$gauge->inc(1024, ['main']);   // +1KB$gauge->dec(512, ['main']);    // -512B

Example 3: Histogram — Value Distribution (Response Time)

A Histogram groups observations into predefined buckets. It is perfect for measuring request execution time or response size.

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