gupalo/prometheus-helper

Prometheus Helper

2.1 2025-12-02 09:51 UTC

Requires

• php: >=8.3
• ext-json: *
• gupalo/json: *
• promphp/prometheus_client_php: ^2.14
• symfony/http-foundation: ^6.4|^7.4|^8.0

Requires (Dev)

• phpunit/phpunit: ^10.5

Suggests

• ext-redis: Required for Redis storage adapter

MIT

README

Wrapper for PHP Prometheus library - https://github.com/PromPHP/prometheus_client_php

Install

composer require gupalo/prometheus-helper

Usage

Basic Usage

use Gupalo\PrometheusHelper\FileAdapter;
use Gupalo\PrometheusHelper\Prometheus;

$helper = new Prometheus(new FileAdapter('/var/prom'), 'myapp');

// Counter
$helper->inc('requests_total', 'Total requests');
$helper->inc('requests_total', 'Total requests', ['method' => 'GET']);

// Gauge
$helper->gaugeSet(100, 'temperature', 'Current temperature');
$helper->gaugeInc('active_connections', 'Active connections');
$helper->gaugeDec('active_connections', 'Active connections');

// Histogram
$helper->observe(0.5, 'request_duration_seconds', 'Request duration');

// Render metrics
$response = $helper->render();

With Redis Storage (DSN)

use Gupalo\PrometheusHelper\Prometheus;
use Gupalo\PrometheusHelper\RedisAdapter;

$helper = new Prometheus(new RedisAdapter('redis://redis'), 'myapp');
$helper->inc('requests_total', 'Total requests');

Supported DSN formats:

• redis://redis - simple hostname
• redis://redis:6380 - with port
• redis://:password@redis:6379 - with password
• redis://user:password@redis:6379/2 - with user, password and database
• redis://redis:6379/0?timeout=0.5&persistent=true - with options

Symfony Integration

Configure in config/services.yaml:

services:
    Prometheus\Storage\Adapter:
        class: Gupalo\PrometheusHelper\RedisAdapter
        arguments:
            $dsn: '%env(REDIS_DSN)%'
    Gupalo\PrometheusHelper\Prometheus:
        arguments:
            $adapter: '@Prometheus\Storage\Adapter'
            $namespace: 'myapp'

when@dev:
    services:
        Prometheus\Storage\Adapter:
            class: Gupalo\PrometheusHelper\FileAdapter
            arguments:
                $dir: '%kernel.project_dir%/var/prom'

when@test:
    services:
        Prometheus\Storage\Adapter:
            class: Prometheus\Storage\InMemory

Then inject in your services:

class MyService
{
    public function __construct(
        private readonly Prometheus $prometheus,
    ) {}

    public function doSomething(): void
    {
        $this->prometheus->inc('operations_total', 'Total operations');
    }
}

Also see tests for more examples.

Migration from v1 to v2

Ask Claude:

find all PrometheusHelper usages and change to Prometheus
read doc from: vendor/gupalo/prometheus-helper/README.md

Or do it manually:

• update config/services.yaml - add code from "Symfony Integration" section above
• change all use Gupalo\PrometheusHelper\PrometheusHelper; to use Gupalo\PrometheusHelper\Prometheus;
• add to constructor private readonly Prometheus $prometheus,
• change all PrometheusHelper:: to $this->prometheus->