Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/larttyler/prometheus-client

A client library for the Prometheus monitoring system
https://github.com/larttyler/prometheus-client

client php prometheus

Last synced: 4 days ago
JSON representation

A client library for the Prometheus monitoring system

Awesome Lists containing this project

README 

        
## Installation

Run the following command in your project root.



```shell

$ composer require dbstudios/prometheus-client

```



## Getting Started

There are two components that you'll need to set up in order to start using this library. The first is the

`CollectorRegistry`, which acts as a repository for your collectors. There isn't any special configuration to worry

about, all you need is an instance you can can access anywhere in your application.



```php

register($counter);

    

    $gauge = new Gauge($adapter, 'test_gauge', 'Please ignore');

    $registry->register($gauge);

    

    $histogram = new Histogram($adapter, 'test_histogram', 'Please ignore', [

    	1,

    	5,

    	15,

    	50,

    	100

    ]);

    

    $registry->register($histogram);

```



Once a collector is registered, you can either expose them as global variables, or by name via the `CollectorRegistry`

(which needs to be globally accessible in some way).



```php

get('test_counter');

    $testCounter->increment();

    

    $testHistogram = $registry->get('test_histogram');

    $testHistogram->observe(153);

```



## "Strong" Typing

To help enforce types when retrieving collectors from the registry, you can use the `getCounter()`, `getGauge()`, and

`getHistogram()` methods in place of the basic `get()` method.



```php

getCounter('test_counter');

    $counter->increment();

    

    $histogram = $registry->getHistogram('test_gauge');

    // throws DaybreakStudios\PrometheusClient\Exception\CollectorRegistryException due to type mismatch

```



In addition to performing the same `null` checking that `get()` performs, each of those methods will also check that the

collector is of the expected type, and throw an exception if the collector is not. They'll also correctly enable IDE

autocompletion, since those three methods specify the proper return type in their PHPDoc block.



## Using Labels

You must define all of a collector's labels when its registered.



```php

increment([

    	'method' => 'GET',

    	'path' => '/users/me',

    ]);

```



The order in which you specify the labels when using the collector (i.e. in `Counter::increment()` in the example above)

does not matter, however ALL label values must be provided each time. 



## Exporting

You can export data from your registry by setting up an endpoint in your application with code similar to the code

below.



```php

getMimeType());

    echo $renderer->render($registry->collect());

```



## Collectors

Collectors are the interface between your code and Prometheus. The Prometheus spec currently defines 3 supported

collector types, which are documented below.



For more information on the concepts of collectors, please refer to the

[official Prometheus documentation](https://prometheus.io/docs/concepts/metric_types/).



### Counters

Counters are the simplest form of collector. The official Prometheus documentation describes counters like so.



> A _counter_ is a cumulative metric that represents a single

> [monotonically increasing counter](https://en.wikipedia.org/wiki/Monotonic_function) whose value can only increase or

> be reset to zero on restart.



Basically, a counter is a collector that can only increase, usually by increments of one. For example, you might use it

to track the number of requests an application has served, or the number of database queries an application has

executed.



```php

increment();

    $counter->increment([], 3);

```



All arguments to `Counter::increment()` are optional. The first argument is the [labels](#using-labels) to use for

the counter being incremented. The second argument is the step for the increment (defaults to one).



### Gauges

A gauge is very similar to a [counter](#counters). However, unlike counters, they can increase or decrease, and can

even have their current value set to a specific number. The official Prometheus documentation describes gauges like so.



> A _gauge_ is a metric that represents a single numerical value that can arbitrarily go up and down.



A gauge is useful for tracking things like temperature, or CPU or memory usage.



```php

increment();

    $gauge->decrement();

    $gauge->set(1.7);

```



Much like a [counter](#counters), the arguments to `Gauge::increment()` and `Gauge::decrement()` are optional. Both

accept up to two arguments: labels and the step, in that order.



You can use `Gauge::set()` to update the gauge to a specific value. It accepts one or two arguments, the first being

the required value to set the gauge to, and the second optional value being the labels for the gauge.



### Histograms

A histogram is (compared to [counters](#counters) and [gauges](#gauges)) a relatively complex collector. The official

Prometheus documentation describes histograms like so.



> A _histogram_ samples observations (usually things like request durations or response sizes) and counts them in

> configurable buckets. It also provides a sum of all observed values.



Histograms can be useful when you're dealing with a metric that might vary wildly each time it's recorded, and can be

used to separate the recorded metrics into quantiles for easier analysis. For example, a histogram may be useful in

analyzing execution times for different code paths, and recording data in a way that outliers can be easily identified

(such as that one particularly slow piece of code that _you can't make run any faster no matter how many hundreds of

hours you throw at it_).



```php

observe(17);

    $histogram->observe(120);

    $histogram->observe(2700);

    $histogram->observe(7010);

```



Since histograms are often used for timing, there are two built-in utility methods for working with time. Please note

that you will need to install the [`symfony/stopwatch`](https://symfony.com/doc/current/components/stopwatch.html)

component in order to use timing features.



```php

startTimer();

    usleep(10000); // ~10 ms

    $timer->observe(); // Tracks time since Histogram::startTime() was invoked and adds it to the histogram



    $histogram->time(function() {

        usleep(100000); // ~100 ms

    }); // Invokes the callable passed to Histogram::time() and adds the execution time as a value of the histogram

```



By default, histograms track time with millisecond precision. However, a histogram accepts an optional constructor

argument to change this to second precision, if that's better suited for your needs.



```php

time(function() {

        usleep(1100000); // ~1100 ms or 1.1 s

    }); // Adds 1 to the histogram (e.g. `$histogram->observe(1)`)

```



## Adapters

This library provides access to the underlying storage system via adapters. The built-in adapters are documented below.



### Redis

The `DaybreakStudios\PrometheusClient\Adapter\Redis\RedisAdapter` uses Redis to store metrics. To use the Redis adapter,

you simply need to provide it with the host of the Redis instance.



```php

setPort(1234)

    //     - $config->setPassword('MyTotallySecurePassword')



    $adapter = new RedisAdapter($config);

```



Keys in the Redis adapter are automatically prefixed in order to prevent collisions with other keys that might be in

your Redis instance. By default, the prefix is "dbstudios_prom:", but you can change this by providing a second argument

to the constructor of `RedisClientConfiguration`.



### Filesystem

The `DaybreakStudios\PrometheusClient\Adapter\Filesystem\FilesystemAdapter` uses files to store metrics. Data written to

the adapter's files is encoded using PHP's [`serialize()`](http://php.net/manual/en/function.serialize.php) function, so

types will be properly preserved. To use the `FilesystemAdapter`, you will need to specify which directory the adapter

should use to store it's files. In order to prevent data loss, the directory you specify should _only_ be used by

Prometheus.



```php