ns3777k/prometheus-bundle

Symfony bundle for collecting and exposing prometheus metrics

v1.0.2 2020-03-11 22:57 UTC

Requires

• php: ^7.1
• endclothing/prometheus_client_php: ^1.0
• symfony/config: ^4.3.0|^5.0.0
• symfony/dependency-injection: ^4.3.0|^5.0.0
• symfony/http-kernel: ^4.3.0|^5.0.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.16
• phpunit/phpunit: ^9.0

Suggests

• ext-apcu: Required if using APCu as prometheus metrics backend
• ext-redis: Required if using Redis as prometheus metrics backend

MIT

• Nikita Safonov

README

Requirements

• PHP 7.3+
• Symfony 4+

Installing

There are 2 ways to install the bundle: automatically with flex or manually.

Using symfony flex

$ composer require ns3777k/prometheus-bundle

Manually

1. Require the package:

$ composer require ns3777k/prometheus-bundle

1. Register the bundle in config/bundles.php:

<?php

return [
    // ...
    Ns3777k\PrometheusBundle\Ns3777kPrometheusBundle::class => ['all' => true],
];

1. Configure (see below)

Usage

Configuration

config/packages/ns3777k_prometheus.yaml:

ns3777k_prometheus:
  namespace: app
  adapter: in_memory # or apcu or redis

  # listener (read below)
  listener:
    enabled: true
    ignored_routes: []

  # redis adapter settings
  redis:
    host: '127.0.0.1'
    port: 6379
    timeout: 0.1
    read_timeout: 10
    persistent_connections: false
    password:
    database:

To register the metrics route, add to config/routes.yaml:

metrics:
  path: /metrics
  controller: 'Ns3777k\PrometheusBundle\Controller\MetricsController::prometheus'

or:

metrics:
  resource: '@Ns3777kPrometheusBundle/Resources/config/routing.xml'

Builtin listener

By default the listener is turned on and collects only one histogram with request duration in seconds (request_duration_seconds) with 3 labels: code, method and route.

Histogram creates total and count metrics automatically.

Usually you don't wanna collect the metrics for routes like _wdt and metrics (that's the route for /metrics) and that's where listener.ignored_routes comes in.

Common PromQL queries for the listener:

• HTTP Request Rate

rate(request_duration_seconds_sum[5m]) / rate(request_duration_seconds_count[5m])

• HTTP Successful Responses

request_duration_seconds_count{code=~"(2|3).*"}

• HTTP Failed Responses

request_duration_seconds_count{code=~"(4|5).*"}

• HTTP Success Response Time 5m 95p

histogram_quantile(0.95, rate(request_duration_seconds_bucket{code=~"(2|3).*"}[5m]))

Collect own metrics

Builtin listener covers only basic information about the request and response. You can use it to get top 10 requests, slow responses, calculate request rate and etc.

But most of the time you wanna collect your own metrics. It's easy to do using CollectorRegistryInterface (implemented by NamespacedCollectorRegistry).

Histogram example:

<?php

declare(strict_types=1);

namespace App\Weather;

use Ns3777k\PrometheusBundle\Metrics\CollectorRegistryInterface;

class WeatherClient
{
    private $registry;

    public function __construct(CollectorRegistryInterface $registry)
    {
        $this->registry = $registry;
    }

    public function getWeatherForRegion(string $region)
    {
        $histogram = $this->registry->getOrRegisterHistogram(
            'weather_request_duration_seconds',
            'Weather request duration with response information',
            ['region']
        );

        $start = microtime(true);
        // do request
        $duration = microtime(true) - $start;

        $histogram->observe($duration, [$region]);
    }

}

No worries about the namespace. It will be prepended automatically from the bundle's configuration.

Security

Remember that when you add /metrics route it becomes publicly available from the internet.

It's you job to restrict access to it (using nginx for example).