README

Drop-in Prometheus bridge for Laravel on top of promphp/prometheus_client_php.

The package keeps the original Ensi\LaravelPrometheus\... namespace and the Prometheus facade alias, so existing application code can usually switch dependencies without mass refactoring.

Installation

Install the package via Composer:

composer require stepovenko/laravel-prometheus

The package declares replace for ensi/laravel-prometheus, so applications can migrate by swapping the package name in composer.json.

Publish the config if you want to customize bags, routes, or storage:

php artisan vendor:publish --tag=prometheus-config

Version Compatibility

Notes:

• Laravel 12 installs on PHP 8.2+.
• Laravel 13 itself requires PHP 8.3+, so Composer will only resolve it on PHP 8.3+.

Basic Usage

The package registers the Prometheus facade alias automatically. If you prefer explicit imports, use Ensi\LaravelPrometheus\Prometheus.

Register your metrics during bootstrap:

use Ensi\LaravelPrometheus\Prometheus;

public function boot(): void
{
    Prometheus::counter('http_requests_count')->labels(['endpoint', 'code']);
    Prometheus::summary('http_requests_duration_seconds', 60, [0.5, 0.95, 0.99]);
}

Update metric values from your application code:

use Closure;
use Ensi\LaravelPrometheus\Prometheus;
use Illuminate\Support\Facades\Route;

public function handle($request, Closure $next)
{
    $startTime = microtime(true);
    $response = $next($request);

    Prometheus::update('http_requests_count', 1, [Route::current()?->uri, $response->status()]);
    Prometheus::update('http_requests_duration_seconds', microtime(true) - $startTime);

    return $response;
}

Configuration

Example config/prometheus.php structure:

return [
    'default_bag' => 'default',
    'enabled' => env('PROMETHEUS_ENABLED', true),
    'app_name' => env('PROMETHEUS_APP_NAME', env('APP_NAME')),
    'bags' => [
        'default' => [
            'namespace' => env('PROMETHEUS_NAMESPACE', 'app'),
            'route' => 'metrics',
            'basic_auth' => [
                'login' => env('PROMETHEUS_AUTH_LOGIN'),
                'password' => env('PROMETHEUS_AUTH_PASSWORD'),
            ],
            'connection' => [
                'connection' => 'default',
                'bag' => 'default',
            ],
            'label_middlewares' => [
                \Ensi\LaravelPrometheus\LabelMiddlewares\AppNameLabelMiddleware::class,
            ],
            'on_demand_metrics' => [
                \Ensi\LaravelPrometheus\OnDemandMetrics\MemoryUsageOnDemandMetric::class,
            ],
        ],
    ],
];

Bags

A bag is an isolated set of metrics with its own namespace, storage, middleware stack, and scrape route. This is useful when you want to separate technical metrics from business metrics.

Supported Storages

• memory
• apcu
• apcu-ng
• redis
• connection
• null-storage

ext-redis is optional at install time and required only for redis and connection storage modes.

Advanced Usage

Select another bag for metric registration and updates:

Prometheus::bag('business')
    ->counter('orders_count')
    ->labels(['delivery_type', 'payment_method']);

Prometheus::bag('business')
    ->update('orders_count', 1, [$order->delivery_type, $order->payment_method]);

Label Middlewares

Label middlewares add labels globally for a bag or locally for a metric builder chain.

use Ensi\LaravelPrometheus\LabelMiddlewares\LabelMiddleware;

class TenantLabelMiddleware implements LabelMiddleware
{
    public function labels(): array
    {
        return ['tenant'];
    }

    public function values(): array
    {
        return [Tenant::current()->id];
    }
}

Then register the middleware class in bag config:

'label_middlewares' => [
    \App\System\TenantLabelMiddleware::class,
],

On-Demand Metrics

On-demand metrics are refreshed right before scrape and are useful for gauges such as queue size or current memory usage.

use Ensi\LaravelPrometheus\MetricsBag;
use Ensi\LaravelPrometheus\OnDemandMetrics\OnDemandMetric;
use Illuminate\Support\Facades\Queue;

class QueueLengthOnDemandMetric extends OnDemandMetric
{
    public function register(MetricsBag $metricsBag): void
    {
        $metricsBag->gauge('queue_length');
    }

    public function update(MetricsBag $metricsBag): void
    {
        $metricsBag->update('queue_length', Queue::size());
    }
}

Development

composer install
composer test-ci
composer phpstan

Security

Please review our security policy for reporting vulnerabilities.

License

The MIT License (MIT). See LICENSE.md for details.