vntrungld/prometheus-exporter

Prometheus Exporter for Laravel

v1.2.0 2026-02-03 04:00 UTC

Requires

• php: ^7.4|^8.0|^8.1|^8.2|^8.3|^8.4
• illuminate/support: ^6.0|^7.0|^8.0|^9.0|^10.0|^11.0|^12.0
• promphp/prometheus_client_php: ^2.11

Requires (Dev)

• orchestra/testbench: ^4.0|^5.0|^6.0|^7.0|^8.0|^9.0|^10.0
• phpunit/phpunit: ^9.0|^10.0|^11.0

MIT

• Vntrungld

• laravel
• Prometheus Exporter

README

A simple and extensible Prometheus metrics exporter for Laravel applications.

Requirements

• PHP 7.4, 8.0, 8.1, 8.2, 8.3, or 8.4
• Laravel 6.x, 7.x, 8.x, 9.x, 10.x, 11.x, or 12.x

Installation

Install via Composer:

composer require vntrungld/prometheus-exporter

Publish the configuration file:

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

Configuration

The configuration file will be published to config/prometheus-exporter.php:

return [
    // Enable or disable the exporter
    'enabled' => env('PROMETHEUS_EXPORTER_ENABLED', true),

    // Metric namespace prefix
    'namespace' => env('PROMETHEUS_EXPORTER_NAMESPACE', 'laravel'),

    // Endpoint path (e.g., /metrics)
    'path' => env('PROMETHEUS_EXPORTER_PATH', 'metrics'),

    // Optional security token
    'token' => env('PROMETHEUS_EXPORTER_TOKEN'),

    // Middleware for the metrics endpoint
    'middleware' => [
        \Vntrungld\PrometheusExporter\Middlewares\Authorize::class,
    ],

    // Tier-based collector configuration (useful for K8s deployments)
    'tier' => env('PROMETHEUS_EXPORTER_TIER', 'default'),

    'tiers' => [
        'default' => [
            'collectors' => [
                \Vntrungld\PrometheusExporter\Collectors\TestCollector::class,
            ],
            'sets' => [],
        ],
    ],
];

Usage

Accessing Metrics

Once installed, metrics are available at the configured endpoint:

GET /metrics

If you've configured a security token:

GET /metrics?token=your-token

Creating Custom Collectors

Create a collector by implementing the Collector interface:

<?php

namespace App\Collectors;

use Vntrungld\PrometheusExporter\Collectors\Collector;
use Vntrungld\PrometheusExporter\Prometheus;

class RequestsCollector implements Collector
{
    public function register(Prometheus $prometheus): void
    {
        $prometheus->addCounter('http_requests_total')
            ->help('Total number of HTTP requests')
            ->labels(['method', 'status'])
            ->value(100, ['GET', '200'])
            ->value(50, ['POST', '201']);
    }
}

Register your collector in the configuration:

'tiers' => [
    'default' => [
        'collectors' => [
            \App\Collectors\RequestsCollector::class,
        ],
        'sets' => [],
    ],
],

Metric Types

Counter

A counter is a cumulative metric that only increases:

$prometheus->addCounter('jobs_processed_total')
    ->help('Total number of processed jobs')
    ->labels(['queue'])
    ->value(150, ['default'])
    ->value(75, ['emails']);

Gauge

A gauge represents a value that can go up or down:

$prometheus->addGauge('queue_size')
    ->help('Current queue size')
    ->labels(['queue'])
    ->value(42, ['default']);

Histogram

A histogram samples observations and counts them in configurable buckets:

$prometheus->addHistogram('http_request_duration_seconds')
    ->help('HTTP request duration in seconds')
    ->labels(['endpoint'])
    ->value(0.25, ['/api/users']);

Summary

A summary samples observations and provides quantiles:

$prometheus->addSummary('http_request_duration_summary')
    ->help('HTTP request duration summary')
    ->labels(['endpoint'])
    ->value(0.25, ['/api/users']);

Collector Sets

Group related collectors using the CollectorSet interface:

<?php

namespace App\Collectors;

use Vntrungld\PrometheusExporter\Collectors\CollectorSet;

class ApiCollectorSet implements CollectorSet
{
    public function collectors(): array
    {
        return [
            RequestsCollector::class,
            ResponseTimeCollector::class,
            ErrorsCollector::class,
        ];
    }
}

Register the set in configuration:

'tiers' => [
    'api' => [
        'collectors' => [],
        'sets' => [
            \App\Collectors\ApiCollectorSet::class,
        ],
    ],
],

Multi-Tier Configuration

For Kubernetes deployments with multiple application tiers:

'tier' => env('PROMETHEUS_EXPORTER_TIER', 'default'),

'tiers' => [
    'default' => [
        'collectors' => [TestCollector::class],
        'sets' => [],
    ],
    'api' => [
        'collectors' => [],
        'sets' => [ApiCollectorSet::class],
    ],
    'worker' => [
        'collectors' => [],
        'sets' => [WorkerCollectorSet::class],
    ],
],

Set the tier via environment variable:

PROMETHEUS_EXPORTER_TIER=api

Using the Facade

You can also use the Prometheus facade directly:

use Vntrungld\PrometheusExporter\Facades\Prometheus;

Prometheus::addCounter('custom_metric')
    ->help('A custom metric')
    ->value(1);

Security

Token Authentication

Set a security token to protect your metrics endpoint:

PROMETHEUS_EXPORTER_TOKEN=your-secret-token

Access metrics with the token:

GET /metrics?token=your-secret-token

Custom Middleware

Add your own middleware for additional security:

'middleware' => [
    \Vntrungld\PrometheusExporter\Middlewares\Authorize::class,
    \App\Http\Middleware\IpWhitelist::class,
],

First Party Collectors

• Horizon Collector - Laravel Horizon metrics
• PHP-FPM Collector - PHP-FPM pool metrics

Testing

Run the test suite:

composer test

Or directly with PHPUnit:

vendor/bin/phpunit

Changelog

Please see the changelog for more information on what has changed recently.

Contributing

Please see contributing.md for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Lam Duc Trung
• All Contributors

License

MIT License. Please see the license file for more information.