laravel-prometheus-exporter

A prometheus exporter for Laravel.

This package is a wrapper bridging endclothing/prometheus_client_php into Laravel.

Installation

composer require superbalist/laravel-prometheus-exporter

Register the service provider in app.php

'providers' => [
    // ...
    Superbalist\LaravelPrometheusExporter\PrometheusServiceProvider::class,
]

Register the facade in app.php

'aliases' => [
    // ...
    'Prometheus' => Superbalist\LaravelPrometheusExporter\PrometheusFacade::class,
]

Configuration

The package has a default configuration which uses the following environment variables.

PROMETHEUS_NAMESPACE=app

PROMETHEUS_METRICS_ROUTE_ENABLED=true
PROMETHEUS_METRICS_ROUTE_PATH=metrics
PROMETHEUS_METRICS_ROUTE_MIDDLEWARE=null

PROMETHEUS_STORAGE_ADAPTER=memory

REDIS_HOST=localhost
REDIS_PORT=6379
PROMETHEUS_REDIS_PREFIX=PROMETHEUS_

To customize the configuration file, publish the package configuration using Artisan.

php artisan vendor:publish --provider="Superbalist\LaravelPrometheusExporter\PrometheusServiceProvider"

You can then edit the generated config at app/config/prometheus.php.

Storage Adapters

The storage adapter is used to persist metrics across requests. The memory adapter is enabled by default, meaning data will only be persisted across the current request. We recommend using the redis or apc adapter in production environments.

The PROMETHEUS_STORAGE_ADAPTER env var is used to specify the storage adapter.

If redis is used, the REDIS_HOST and REDIS_PORT vars also need to be configured.

Exporting Metrics

The package adds a /metrics end-point, enabled by default, which exposes all metrics gathered by collectors.

This can be turned on/off using the PROMETHEUS_METRICS_ROUTE_ENABLED var, and can also be changed using the PROMETHEUS_METRICS_ROUTE_PATH var.

If you would like to protect this end-point, you can write any custom middleware and enable it using PROMETHEUS_METRICS_ROUTE_MIDDLEWARE.

Collectors

A collector is a class, implementing the CollectorInterface, which is responsible for collecting data for one or many metrics.

Please see the ExampleCollector included in this repository.

You can auto-load your collectors by adding them to the collectors array in the prometheus.php config.

Usage

// retrieve the exporter
$exporter = app(\Superbalist\LaravelPrometheusExporter::class);
// or
$exporter = app('prometheus');
// or
$exporter = Prometheus::getFacadeRoot();

// register a new collector
$collector = new \My\New\Collector();
$exporter->registerCollector($collector);

// retrieve all collectors
var_dump($exporter->getCollectors());

// retrieve a collector by name
$collector = $exporter->getCollector('user');

// export all metrics
// this is called automatically when the /metrics end-point is hit
var_dump($exporter->export());

// the following methods can be used to create and interact with counters, gauges and histograms directly
// these methods will typically be called by collectors, but can be used to register any custom metrics directly,
// without the need of a collector

// create a counter
$counter = $exporter->registerCounter('search_requests_total', 'The total number of search requests.');
$counter->inc(); // increment by 1
$counter->incBy(2);

// create a counter (with labels)
$counter = $exporter->registerCounter('search_requests_total', 'The total number of search requests.', ['request_type']);
$counter->inc(['GET']); // increment by 1
$counter->incBy(2, ['GET']);

// retrieve a counter
$counter = $exporter->getCounter('search_requests_total');

// create a gauge
$gauge = $exporter->registerGauge('users_online_total', 'The total number of users online.');
$gauge->inc(); // increment by 1
$gauge->incBy(2);
$gauge->dec(); // decrement by 1
$gauge->decBy(2);
$gauge->set(36);

// create a gauge (with labels)
$gauge = $exporter->registerGauge('users_online_total', 'The total number of users online.', ['group']);
$gauge->inc(['staff']); // increment by 1
$gauge->incBy(2, ['staff']);
$gauge->dec(['staff']); // decrement by 1
$gauge->decBy(2, ['staff']);
$gauge->set(36, ['staff']);

// retrieve a gauge
$counter = $exporter->getGauge('users_online_total');

// create a histogram
$histogram = $exporter->registerHistogram(
    'response_time_seconds',
    'The response time of a request.',
    [],
    [0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]
);
// the buckets must be in asc order
// if buckets aren't specified, the default 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0 buckets will be used
$histogram->observe(5.0);

// create a histogram (with labels)
$histogram = $exporter->registerHistogram(
    'response_time_seconds',
    'The response time of a request.',
    ['request_type'],
    [0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]
);
// the buckets must be in asc order
// if buckets aren't specified, the default 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0 buckets will be used
$histogram->observe(5.0, ['GET']);

// retrieve a histogram
$counter = $exporter->getHistogram('response_time_seconds');