liveintent/laravel-prometheus-exporter

Prometheus exporter for laravel metrics.

v1.4.1 2021-08-24 17:04 UTC

Requires

• php: ^7.4|^8.0
• illuminate/contracts: ^8.0
• nesbot/carbon: ^2.46
• promphp/prometheus_client_php: ^2.2

Requires (Dev)

• brianium/paratest: ^6.2
• friendsofphp/php-cs-fixer: ^3.0
• liveintent/php-cs-rules: ^1.0
• nunomaduro/collision: ^5.3
• orchestra/testbench: ^6.15
• phpunit/phpunit: ^9.3
• vimeo/psalm: ^4.4

MIT

• laravel
• exporter
• prometheus
• liveintent

README

This is a Laravel package that automatically collects data and exposes a /metrics endpoint in your application which can then be scraped by Prometheus.

For a full list of exported metrics, see exporters.

Installation

You can install the package via composer:

composer require liveintent/laravel-prometheus-exporter

Once installed run the following command to generate the metrics config file.

php artisan metrics:install

The package will auto-register itself.

Usage

The metrics config file contains a list of enabled exporters. Each exporter will collect data and store it in your configured data store.

Storage

The storage drivers currently supperted are redis, apc, and in-memory. You may adjust this value by setting the env METRICS_STORAGE_DRIVER.

The package uses the in-memory driver by default to help you get started, but you should change this as soon as you are ready as it's not useful for much beyond testing.

You will need the appropriate pecl extension installed (apc or php-redis).

If you need to clear the storage, you may do so with:

php artisan metrics:clear

Exporters

Request Duration Historam Exporter - http_request_duration_seconds_bucket

This will export histogram data for request duration.

Example

Exporters\RequestDurationHistogramExporter::class => [
    'enabled' => env('EXPORT_REQUEST_DURATION_HISTOGRAM', true),
    'options'
        'buckets' => [
            5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 200
        ],
    ],
],

Labels

name	description	example
service	name of the service	my-amazing-api
environment	the environment	qa, prod, etc
response_code	the http response code	200, 400, etc
method	the http method	GET, POST, etc
path	the uri of the request	/, /posts, etc

Request Memory Usage Historam Exporter - http_request_memory_usage_bytes

This will export histogram data for request memory usage.

Example

Exporters\RequestMemoryUsageHistogramExporter::class => [
    'enabled' => env('EXPORT_MEMORY_USAGE_HISTOGRAM', true),
    'options'
        'buckets' => [
            5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 200
        ],
    ],
],

Labels

name	description	example
service	name of the service	my-amazing-api
environment	the environment	qa, prod, etc
code	the http response code	200, 400, etc
method	the http method	GET, POST, etc
path	the uri of the request	/, /posts, etc

Job Processing Time Historam Exporter - job_process_time_seconds_bucket

This will export histogram data for job execution duration.

Example

Exporters\JobProcessTimeHistogramExporter::class => [
    'enabled' => env('EXPORT_JOB_PROCESS_TIME_HISTOGRAM', true),
    'options'
        'buckets' => [
            0.1, .3, .5, .7, 1, 2, 3, 4, 5, 10, 30, 40, 60,
        ],
    ],
],

Labels

name	description	example
service	name of the service	my-amazing-api
environment	the environment	qa, prod, etc
name	the classname of the job	App\\Jobs\\ProcessPayment
status	the job status	procesed, failed

Job Wait Time Historam Exporter - job_wait_time_seconds_bucket

This will export histogram data for the time a job had to wait on the queue.

Note: This exporter relies on Laravel Horizon.

Example

Exporters\JobWaitTimeHistogramExporter::class => [
    'enabled' => env('EXPORT_JOB_WAIT_TIME_HISTOGRAM', true),
    'options'
        'buckets' => [
            0.1, .3, .5, .7, 1, 2, 3, 4, 5, 10, 30, 40, 60,
        ],
    ],
],

Labels

name	description	example
service	name of the service	my-amazing-api
environment	the environment	qa, prod, etc
name	the classname of the job	App\\Jobs\\ProcessPayment

Query Duration Historam Exporter - db_query_time_seconds_bucket

This will export histogram data for query execution times.

Example

Exporters\QueryDurationHistogramExporter::class => [
    'enabled' => env('EXPORT_QUERY_DURATION_HISTOGRAM', true),
    'options'
        'buckets' => [
            5, 10, 15, 20, 30, 40, 50, 60, 70, 80, 90, 100, 200
        ],
    ],
],

Labels

name	description	example
service	name of the service	my-amazing-api
environment	the environment	qa, prod, etc
sql	the sql query	SELECT * FROM `users`

Writing New Exporters

You may also write your own exporter. You only need to implement two methods, register and export.

The following example increments a counter every time the / route is visited.

<?php

namespace LiveIntent\LaravelPrometheusExporter\Exporters;

use Illuminate\Foundation\Http\Events\RequestHandled;

class HomePageVisitsCountExporter extends Exporter
{
    /**
     * Register the watcher.
     *
     * @return void
     */
    public function register()
    {
        $this->app['events']->listen(RequestHandled::class, [$this, 'export']);
    }

    /**
     * Export metrics.
     *
     * @param  \Illuminate\Foundation\Http\Events\RequestHandled  $event
     * @return void
     */
    public function export($event)
    {
        $uri =  str_replace($event->request->root(), '', $event->request->fullUrl()) ?: '/';
        
        if ($uri === '/') {
            $counter = $this->registry->getOrRegisterCounter(
                '', 'home_page_visits_counter', 'it is a silly example'
            );

            $counter->inc();
        }
    }
}

Register your Exporter class by placing it in the list of exporters found in the metrics config file.