aduzenko/laravel-configurable-prometheus

A package providing configurable interface to export Prometheus metrics in Laravel

v1.0.0 2025-05-03 16:21 UTC

Requires

• php: ^8.3
• ext-redis: *
• illuminate/config: ^12.0
• illuminate/support: ^12.0
• laravel/framework: ^11.0 || ^12.0
• promphp/prometheus_client_php: ^2.6

Requires (Dev)

• mockery/mockery: ^1.6
• phpunit/phpunit: ^10.0

MIT

• Anatoly Duzenko

README

A Laravel package for defining, managing, and exporting Prometheus metrics in a flexible, extensible way.

✨ Features

• Simple configuration-driven metric definitions
• Full support for Counter, Gauge, Histogram, and Summary
• Designed for Laravel 12 and PHP 8.3+
• Define metrics in your app, not just in the package

🚀 Installation

composer require aduzenko/laravel-configurable-prometheus

⚙️ Publishing config

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

This will publish:

• config/prometheus.php
• example metrics route

🔐 Authentication for report route

The Prometheus endpoint is protected from unauthorized access by basic HTTP authentication.

Step 1: Add credentials to your .env file

PROMETHEUS_USER=prom
PROMETHEUS_PASSWORD=secret

📡 Route setup for Prometheus metrics

The Prometheus endpoint is configurable.

Update route in config/prometheus.php file

'endpoint' => 'prometheus',

🧩 Defining custom metrics

Define a class implementing MetricGroup:

namespace App\Metrics;

use AnatolyDuzenko\ConfigurablePrometheus\DTO\MetricDefinition;
use AnatolyDuzenko\ConfigurablePrometheus\Enums\MetricType;
use AnatolyDuzenko\ConfigurablePrometheus\Contracts\MetricGroup;

class ApiMetrics implements MetricGroup
{
    public function definitions(): array
    {
        return [
            new MetricDefinition(
                namespace: 'api',
                name: 'response_time_seconds',
                helpText: 'API response time',
                type: MetricType::Histogram,
                labelNames: ['route'],
                buckets: [0.1, 0.3, 0.5, 1, 2, 5]
            )
        ];
    }
}

Then reference your group in config/prometheus.php:

'groups' => [
    \App\Metrics\ApiMetrics::class,
],

📈 Usage

// In your class constructor, use
public function __construct(protected MetricManager $metrics)
    {}
// then
$this->metrics->inc('users', 'user_logins_total', ['web']);
$this->metrics->set('users', 'active_users', 42, ['web']);
$this->metrics->observe('api', 'response_time_seconds', 0.32, ['/api/v1']);

Alternate usage

// In your method
public function index(Request $request, MetricManager $metrics)
{
    // ....
    $metrics->inc('users', 'user_logins_total', ['web']);
    $metrics->set('users', 'active_users', 42, ['web']);
    $metrics->observe('api', 'response_time_seconds', 0.32, ['/api/v1']);
}

🧪 Testing

vendor/bin/phpunit

📄 License

MIT © Anatoly Duzenko