Prometheus Client PHP

prometheus_client_php is a Prometheus client library for instrumenting PHP applications with metrics. Because PHP worker processes normally share no state, the library performs client-side aggregation through pluggable storage adapters - Redis, Predis, APCu, APCng, or an in-memory backend - so counters and histograms accumulate correctly across requests.

It implements the standard Prometheus metric types (counters, gauges, histograms, summaries) and exposes them in the Prometheus text exposition format, ready to be scraped from a /metrics endpoint. This makes it straightforward to add production-grade observability to PHP-FPM, worker, and CLI applications.

What You Get

• Counter, Gauge, Histogram, and Summary metric types via a CollectorRegistry
• Five storage adapters - Redis, Predis, APC, APCng, and in-memory - for cross-process aggregation
• A renderer that outputs metrics in the Prometheus text exposition format for /metrics
• Label support for dimensional metrics with named label sets
• Interfaces (RegistryInterface, Adapter, RendererInterface) for extending storage and output

Common Use Cases

• Exposing application metrics from a PHP /metrics endpoint for Prometheus to scrape
• Counting requests, errors, and business events across PHP-FPM worker processes
• Measuring request latency distributions with histograms
• Tracking live gauges like queue depth or active connections

Under The Hood

Architecture - The core lives in src/Prometheus, where CollectorRegistry holds registered metrics and delegates persistence to a swappable Storage\Adapter. Metric classes (Counter, Gauge, Histogram, Summary) extend a common Collector base and write samples into the adapter keyed by name and labels. A RenderTextFormat renderer walks MetricFamilySamples to produce the Prometheus exposition text. The adapter abstraction is what solves PHP’s shared-nothing problem: state lives in Redis/APCu rather than the process.

Tech Stack - Pure PHP (7.4+/8.x), distributed via Composer. Optional runtime backends are Redis (phpredis or Predis) and APCu. CI runs the test matrix via GitHub Actions with PHPUnit.

Code Quality - The codebase is interface-driven (RegistryInterface, Adapter, RendererInterface), which keeps storage and rendering concerns cleanly separated and testable. It ships a substantial PHPUnit suite exercising each adapter, and a Math.php helper isolates the trickier histogram/quantile calculations.

API Design - The public API mirrors the official Prometheus client conventions: get a registry, register or fetch a metric by namespace/name/help/labels, then inc, set, or observe. This familiarity makes it easy for anyone who has used a Prometheus client in another language, and the adapter choice is a single constructor argument.