ensi / laravel-prometheus
laravel prometheus
Installs: 37 461
Dependents: 1
Suggesters: 0
Security: 0
Stars: 2
Watchers: 3
Forks: 1
Open Issues: 1
Requires
- php: ^8.1
- ext-redis: *
- laravel/framework: ^9.0 || ^10.0 || ^11.0
- promphp/prometheus_client_php: ^2.6
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.2
- nunomaduro/collision: ^6.0 || ^7.0 || ^8.1
- orchestra/testbench: ^7.0 || ^8.0 || ^9.0
- pestphp/pest: ^1.22 || ^2.0
- pestphp/pest-plugin-laravel: ^1.1 || ^2.0
- phpstan/extension-installer: ^1.3
- phpstan/phpstan: ^1.11
- spaze/phpstan-disallowed-calls: ^2.15
This package is auto-updated.
Last update: 2024-10-17 12:19:01 UTC
README
Adapter for promphp/prometheus_client_php
Installation
You can install the package via composer:
composer require ensi/laravel-prometheus
Publish the config with:
php artisan vendor:publish --provider="Ensi\LaravelPrometheus\PrometheusServiceProvider"
Version Compatibility
Basic Usage
Before you wind up the metric counters, you need to register them. The best thing to do is to use the boot() method from the application service provider.
# app/Providers/AppServiceProvider.php public function boot() { Prometheus::counter('http_requests_count')->labels(['endpoint', 'code']); Prometheus::summary('http_requests_duration_seconds', 60, [0.5, 0.95, 0.99]); }
Updating the counter value is just as easy
# app/Http/Middleware/Telemetry.php public function handle($request, Closure $next) { $startTime = microtime(true); $response = $next($request); $endTime = microtime(true); Prometheus::update('http_requests_count', 1, [Route::current()?->uri, $response->status()]); Prometheus::update('http_requests_duration_seconds', $endTime - $startTime); return $response; }
Configuration
The structure of the configuration file
# config/prometheus.php return [ 'default_bag' => '<bag-name>', 'enabled' => env('PROMETHEUS_ENABLED', true), 'app_name' => env('PROMETHEUS_APP_NAME', env('APP_NAME')), 'bags' => [ '<bag-name>' => [ 'namespace' => '<prometheus-namespace>', 'route' => '<path-of-scrape-endpoint>', 'basic_auth' => [ 'login' => env('PROMETHEUS_AUTH_LOGIN'), 'password' => env('PROMETHEUS_AUTH_PASSWORD'), ], '<storage-type>' => [ '<connection-parameters>' ], 'label_middlewares' => [ '<middleware-class>' ], 'on_demand_metrics' => [ '<on-demand-metric-class>' ] ], ], ];
Bag
You may want to have several sets of metrics, for example, one set with technical metrics, such as the number of http requests or unexpected exceptions, and a second set for business values, such as the number of orders or impressions of a particular page. To do this, the concept of bag is introduced. You can configure several bugs by specifying your own data warehouse for each, a separate endpoint for collecting metrics, etc.
Storage type
You can use all the storage (Adapters) from the promphp/prometheus_client_php package. In addition, you can specify the name of the redis connection from the file config/databases.php
.
Storage configuration options.
Store metrics in the process memory.
'memory' => true
Use apcupsd
'apcu' => [ 'prefix' => 'metrics' ]
or an alternative APCuNG adapter
'apcu-ng' => [ 'prefix' => 'metrics' ]
A Redis adapter that will create a phpredis connection by itself
'redis' => [ 'host' => '127.0.0.1', 'port' => 6379, 'timeout' => 0.1, 'read_timeout' => '10', 'persistent_connections' => false, 'password' => null, 'prefix' => 'my-app', 'bag' => 'my-metrics-bag' ]
Laravel Redis connection from config/databases.php
. The same Redis adapter will be created under the hood, but it will take the native phpredis connection object from laravel's Redismanager.
'connection' => [ 'connection' => 'default', 'bag' => 'default', ]
Advanced Usage
You can select another bag to create and update metrics in it using the bag($bagName)
method.
# app/Providers/AppServiceProvider.php public function boot() { // создаём метрики в конкретном bag Prometheus::bag('business')->counter('orders_count')->labels(['delivery_type', 'payment_method']) } # app/Actions/CreateOrder.php public function execute(Order $order) { // ... Prometheus::bag('business')->update('orders_count', 1, [$order->delivery_type, $order->payment_method]); }
Label Middlewares
You can add a label to all bagmetrics by specifying the so-called Label middleware in its configuration. Label middleware is triggered at the moment the metric is determined and at the moment its counter is updated, adding in the first case to the label name, and in the second case the value.
For example, we have a TenantLabelProvider
class TenantLabelMiddleware implements LabelMiddleware { public function labels(): array { return ['tenant']; } public function values(): array { return [Tenant::curent()->id]; } }
We register it in the bag configuration.
# config/prometheus.php return [ // ... 'bags' => [ 'default' => [ // ... 'label_middlewares' => [ \App\System\TenantLabelMiddleware::class, ] ], ], ];
Then, as usual, we work with metrics.
Prometheus::counter('http_requests_count')->labels(['endpoint', 'code']); // ... Prometheus::update('http_requests_count', 1, [Route::current()?->uri, $response->status()]);
As a result, the metric will have not two, but three labels
app_http_requests_count{endpoint="catalog/products",code="200",tenant="JBZ-987-H6"} 987
On demand metrics
Sometimes metrics are not linked to application events. Usually these are metrics of the gauge type, which it makes no sense to update on each incoming request, because prometheus will still take only the last set value. Such metrics can be calculated at the time of collection of metrics by prometheus. To do this, you need to create a so-called on demand metric. This is the class in which you register metrics and set values in them.
class QueueLengthOnDemandMetric extends OnDemandMetric { public function register(MetricsBag $metricsBag): void { $metricsBag->gauge('queue_length'); } public function update(MetricsBag $metricsBag): void { $metricsBag->update('queue_length', Queue::size()); } }
The update of such metrics occurs at the moment prometheus addresses the endpoint of obtaining metrics.
Contributing
Please see CONTRIBUTING for details.
Testing
- composer install
- composer test
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
License
The MIT License (MIT). Please see License File for more information.