add documentation to readme and sample ExampleCollector.php
This commit is contained in:
Matthew Goslett
parent
78a0916b15
commit
00cb369d0b
2 changed files with 171 additions and 2 deletions
113
README.md
113
README.md
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
A prometheus exporter for Laravel.
|
||||
|
||||
**This package is still under active development.**
|
||||
|
||||
[](https://twitter.com/superbalist)
|
||||
[](https://travis-ci.org/Superbalist/laravel-prometheus-exporter)
|
||||
[](LICENSE)
|
||||
|
|
@ -56,10 +58,117 @@ php artisan vendor:publish --provider="Superbalist\LaravelPrometheusExporter\Pro
|
|||
|
||||
You can then edit the generated config at `app/config/prometheus.php`.
|
||||
|
||||
// TODO:
|
||||
### 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](src/CollectorInterface.php), which is responsible for
|
||||
collecting data for one or many metrics.
|
||||
|
||||
Please see the [ExampleCollector](src/ExampleCollector.php) included in this repository.
|
||||
|
||||
You can auto-load your collectors by adding them to the `collectors` array in the prometheus.php config.
|
||||
|
||||
## Usage
|
||||
|
||||
```php
|
||||
// TODO:
|
||||
// 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->obeserve(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->obeserve(5.0, ['GET']);
|
||||
|
||||
// retrieve a histogram
|
||||
$counter = $exporter->getHistogram('response_time_seconds');
|
||||
```
|
||||
|
|
|
|||
60
src/ExampleCollector.php
Normal file
60
src/ExampleCollector.php
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
<?php
|
||||
|
||||
namespace Superbalist\LaravelPrometheusExporter;
|
||||
|
||||
use Prometheus\Gauge;
|
||||
|
||||
class ExampleCollector implements CollectorInterface
|
||||
{
|
||||
/**
|
||||
* @var Gauge
|
||||
*/
|
||||
protected $usersRegisteredGauge;
|
||||
|
||||
/**
|
||||
* Return the name of the collector.
|
||||
*
|
||||
* @return string
|
||||
*/
|
||||
public function getName()
|
||||
{
|
||||
return 'users';
|
||||
}
|
||||
|
||||
/**
|
||||
* Register all metrics associated with the collector.
|
||||
*
|
||||
* The metrics needs to be registered on the exporter object.
|
||||
* eg:
|
||||
* ```php
|
||||
* $exporter->registerCounter('search_requests_total', 'The total number of search requests.');
|
||||
* ```
|
||||
*
|
||||
* @param PrometheusExporter $exporter
|
||||
*/
|
||||
public function registerMetrics(PrometheusExporter $exporter)
|
||||
{
|
||||
$this->usersRegisteredGauge = $exporter->registerGauge(
|
||||
'users_registered_total',
|
||||
'The total number of registered users.',
|
||||
['group']
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Collect metrics data, if need be, before exporting.
|
||||
*
|
||||
* As an example, this may be used to perform time consuming database queries and set the value of a counter
|
||||
* or gauge.
|
||||
*/
|
||||
public function collect()
|
||||
{
|
||||
// retrieve the total number of staff users registered
|
||||
// eg: $totalUsers = Users::where('group', 'staff')->count();
|
||||
$this->usersRegisteredGauge->set(36, ['staff']);
|
||||
|
||||
// retrieve the total number of regular users registered
|
||||
// eg: $totalUsers = Users::where('group', 'regular')->count();
|
||||
$this->usersRegisteredGauge->set(192, ['regular']);
|
||||
}
|
||||
}
|
||||
Loading…
Reference in a new issue