Prometheus Package

Prometheus client library using database, memory storage.

Based on documentation https://prometheus.io/docs/instrumenting/writing_clientlibs/ and https://github.com/PromPHP/prometheus_client_php

Use rancoud/Database package (https://github.com/rancoud/Database) when using MySQL, PostgreSQL or SQLite.

Installation

composer require rancoud/prometheus

How to use it?

Counter metric example

Simple counter and expose result

useRancoud\Prometheus\Counter;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Storage\InMemory;
// Define a counter$counter = newCounter(
newInMemory(), // <- InMemory is the storage engine used.newDescriptor("login") // <- Descriptor describe your metric.
);
// By default it increase by 1$counter->inc();
// Also you can use a value other than 1 (always positive in case of counter)$counter->inc(3);
// Now you can expose as plain text resultecho$counter->expose();
// Result of expose() below:#TYPE login counter
login 4

Counter with help text and labels

useRancoud\Prometheus\Counter;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Storage\InMemory;
$descriptor = newDescriptor("request_count", ['method', 'path'])
->setHelp('Number of request by method and path');
$counter = newCounter(newInMemory(), $descriptor);
$counter->inc(5, ['GET', 'home']);
$counter->inc(3, ['GET', 'login']);
$counter->inc(1, ['POST', 'login']);
echo$counter->expose();
// Result of expose() below:#HELP request_count Number of request by method and path#TYPE request_count counter
request_count{method="GET",path="home"} 5
request_count{method="GET",path="login"} 3
request_count{method="POST",path="login"} 1

Gauge metric example

useRancoud\Prometheus\Gauge;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Storage\InMemory;
// Define a gauge$gauge = newGauge(
newInMemory(),
newDescriptor("account_count")
->setHelp('Number of account')
);
// You can set a value$gauge->set(100);
// You can increment$gauge->inc(15);
// You can decrement$gauge->dec(5);
echo$gauge->expose();
// Result of expose() below:#HELP account_count Number of account#TYPE account_count gauge
account_count 110

Histogram metric example

useRancoud\Prometheus\Histogram;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Storage\InMemory;
// Define a histogram$histogram = newHistogram(
newInMemory(),
newDescriptor("http_request_duration_seconds")
);
// You can observe a value$histogram->observe(0.56);
echo$histogram->expose();
// Result of expose() below:#TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{le="0.005"} 0
http_request_duration_seconds_bucket{le="0.01"} 0
http_request_duration_seconds_bucket{le="0.025"} 0
http_request_duration_seconds_bucket{le="0.05"} 0
http_request_duration_seconds_bucket{le="0.075"} 0
http_request_duration_seconds_bucket{le="0.1"} 0
http_request_duration_seconds_bucket{le="0.25"} 0
http_request_duration_seconds_bucket{le="0.5"} 0
http_request_duration_seconds_bucket{le="0.75"} 1
http_request_duration_seconds_bucket{le="1"} 1
http_request_duration_seconds_bucket{le="2.5"} 1
http_request_duration_seconds_bucket{le="5"} 1
http_request_duration_seconds_bucket{le="7.5"} 1
http_request_duration_seconds_bucket{le="10"} 1
http_request_duration_seconds_bucket{le="+Inf"} 1
http_request_duration_seconds_count 1
http_request_duration_seconds_sum 0.56

You can set your own buckets.

newDescriptor("http_request_duration_seconds")->setHistogramBuckets([0, 5, 10]);

Summary metric example

useRancoud\Prometheus\Summary;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Storage\InMemory;
// Define a summary$summary = newSummary(
newInMemory(),
newDescriptor("http_request_duration_seconds")
);
// You can observe a value$summary->observe(0.56);
echo$summary->expose();
// Result of expose() below:#TYPE http_request_duration_seconds summary
http_request_duration_seconds{quantile="0.01"} 0.56
http_request_duration_seconds{quantile="0.05"} 0.56
http_request_duration_seconds{quantile="0.5"} 0.56
http_request_duration_seconds{quantile="0.95"} 0.56
http_request_duration_seconds{quantile="0.99"} 0.56
http_request_duration_seconds_count 1
http_request_duration_seconds_sum 0.56

You can set your own quantiles.

newDescriptor("http_request_duration_seconds")->setSummaryQuantiles([0.1, 0.5, 0.9]);

You can change the TTL in seconds you want to keep the observed values.

newDescriptor("http_request_duration_seconds")->setSummaryTTL(10);

Registry

A registry is an object where all metrics are stored.

Registry instance example

useRancoud\Prometheus\Counter;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Registry;
useRancoud\Prometheus\Storage\InMemory;
// Define a registry$registry = newRegistry();
// Define 2 counters$counter1 = newCounter(newInMemory(), newDescriptor("login"));
$counter2 = newCounter(newInMemory(), newDescriptor("logout"));
// Add counters in registry$registry->register($counter1, $counter2);
// Update counters otherwise is not exposed$counter1->inc(4);
$counter2->inc(2);
// Now you can expose as plain text resultecho$registry->expose();
// Result of expose() below:#TYPE login counter
login 4#TYPE logout counter
logout 2

Default Registry with static Singleton example

useRancoud\Prometheus\Counter;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Registry;
useRancoud\Prometheus\Storage\InMemory;
// Define 2 counters AND register them in the default registry$counter1 = newCounter(newInMemory(), newDescriptor("login"))->register();
$counter2 = newCounter(newInMemory(), newDescriptor("logout"))->register();
// Update counters otherwise is not exposed$counter1->inc(4);
$counter2->inc(2);
// Now you can expose as plain text resultecho Registry::getDefault()->expose();
// Result of expose() below:#TYPE login counter
login 4#TYPE logout counter
logout 2

Database storage example

Using SQLite with memory database is same as using InMemory Database.

useRancoud\Database\Configurator;
useRancoud\Database\Database;
useRancoud\Prometheus\Counter;
useRancoud\Prometheus\Descriptor;
useRancoud\Prometheus\Storage\SQLite;
$params = [
'driver' => 'sqlite',
'host' => '',
'user' => '',
'password' => '',
'database' => 'prometheus.db'
];
$configurator = newConfigurator($params);
$database = newDatabase($configurator);
$storage = newSQLite($database);
$counter = newCounter($storage, newDescriptor("example"));

Collector (metric)

Constructor

publicfunction __construct(Adapter$storage, Descriptor$descriptor)

Returns raw metrics (descriptor + samples) as iterable.

publicfunction collect(): iterable

Returns text of metric as string.

publicfunction expose(): string

Returns metric name.

publicfunction metricName(): string

Register in the default Registry.

publicfunction register(): self

Counter Metric

Increments counter.

publicfunction inc(float|int$value = 1, array$labels = []): void

Gauge Metric

Increments counter.

publicfunction inc(float|int$value = 1, array$labels = []): void

Decrements counter.

publicfunction dec(float|int$value = 1, array$labels = []): void

Sets value of gauge.

publicfunction set(float|int$value, array$labels = []): void

Sets value of gauge with function \time() to use current Unix timestamp.

publicfunction setToCurrentTime(array$labels = []): void

Histogram Metric

Adds a new sample.

publicfunction observe(float$value, array$labels = []): void

Generates linear buckets.
Creates 'count' regular buckets, each 'width' wide, where the lowest bucket has an upper bound of 'start'.

publicstaticfunction linearBuckets(float$start, float$width, int$countBuckets): array

Generates exponential buckets.
Creates 'count' regular buckets, where the lowest bucket has an upper bound of 'start' and each following bucket's upper bound is 'factor' times the previous bucket's upper bound.

publicstaticfunction exponentialBuckets(float$start, float$growthFactor, int$countBuckets): array

Summary Metric

Adds a new sample.

publicfunction observe(float$value, array$labels = []): void

Descriptor

Constructor

publicfunction __construct(string$name, array$labels = [])

When exposed it will output a line #HELP {your message}.

publicfunction setHelp(string$help): self

Set histogram buckets instead of using default buckets.

publicfunction setHistogramBuckets(array$buckets): self

Set summary TTL instead of using default TTL.

publicfunction setSummaryTTL(int$ttlInSeconds): self

Set summary quantiles instead of using default quantiles.

publicfunction setSummaryQuantiles(array$quantiles): self

Returns name.

publicfunction name(): string

Returns labels.

publicfunction labels(): array

Returns labels count.

publicfunction labelsCount(): int

Returns histogram buckets.

publicfunction buckets(): array

Returns summary quantiles.

publicfunction quantiles(): array

Returns summary TTL.

publicfunction ttlInSeconds(): int

Exports HELP.

publicfunction exportHelp(): string

Exports TYPE.

publicfunction exportType(string$type): string

Exports value (counter, gauge, histogram _sum and _count, summary _sum and _count).

publicfunction exportValue(float|int$value, array$labelValues, string$suffixName = ''): string

Exports value (histogram).

publicfunction exportHistogramValue(string$bucket, int$value, array$labelValues): string

Exports value (summary).

publicfunction exportSummaryValue(float$quantile, array$values, array$labelValues): string

Registry

Registers metric.

publicfunction register(Collector ...$collectors): void

Unregisters metric.

publicfunction unregister(Collector ...$collectors): void

Returns raw metrics registered (descriptor + samples) as iterable.

publicfunction collect(): iterable

Returns text of metrics registered as string.

publicfunction expose(): string

Registers metric in the default Registry (singleton).

publicstaticfunction registerInDefault(Collector$collector): void

Returns the default Registry (singleton).

publicstaticfunction getDefault(): self

Storage (Adapter interface)

Returns metrics (counter, gauge, histogram and summary) as iterable.
If metric type and name is provided it will return only the specify metric.

publicfunction collect(string$metricType = '', string$metricName = ''): iterable

Returns text of metrics (counter, gauge, histogram and summary) as iterable.
If metric type and name is provided it will return only the specify metric.

publicfunction expose(string$metricType = '', string$metricName = ''): iterable

Updates counter metric.

publicfunction updateCounter(Descriptor$descriptor, float|int$value = 1, array$labelValues = []): void

Updates gauge metric.

publicfunction updateGauge(Descriptor$descriptor, Operation$operation, float|int$value = 1, array$labelValues = []): void

Adds sample to histogram metric.

publicfunction updateHistogram(Descriptor$descriptor, float$value, array$labelValues = []): void

Adds sample to summary metric.

publicfunction updateSummary(Descriptor$descriptor, float$value, array$labelValues = []): void

Removes all data saved.

publicfunction wipeStorage(): void

Overrides Time Function for summary metric.

publicfunction setTimeFunction(callable|string$time): void

InMemory

Returns text of counters metric as iterable.

publicfunction exposeCounters(string$metricName = ''): iterable

Returns text of gauges metric as iterable.

publicfunction exposeGauges(string$metricName = ''): iterable

Returns text of histograms metric as iterable.

publicfunction exposeHistograms(string$metricName = ''): iterable

Returns text of summaries metric as iterable.

publicfunction exposeSummaries(string$metricName = ''): iterable

SQLite

Returns text of counters metric as iterable.

publicfunction exposeCounters(string$metricName = ''): iterable

Returns text of gauges metric as iterable.

publicfunction exposeGauges(string$metricName = ''): iterable

Returns text of histograms metric as iterable.

publicfunction exposeHistograms(string$metricName = ''): iterable

Returns text of summaries metric as iterable.

publicfunction exposeSummaries(string$metricName = ''): iterable

Remove all expired summaries sample according to the TTL.

publicfunction deleteExpiredSummaries(): void

Drop all tables.

publicfunction deleteStorage(): void

How to Dev

composer ci for php-cs-fixer and phpunit and coverage
composer lint for php-cs-fixer
composer test for phpunit and coverage