chaseisabelle/phprom-client

v0.0.5 2020-11-21 14:47 UTC

This package is auto-updated.

Last update: 2022-09-17 04:22:47 UTC


README

a client lib for phprom, a prometheus metric datastore for php apps

example

see a fully functional example here

prerequisites

install and run the server

install

  • install the client or bundle
    • composer require chaseisabelle/phprom-client
    • composer require chaseisabelle/phprom-bundle

install grpc requirements

  • NOTE: this is only required if you are using the grpc api
  • install grpc
    • composer require 'grpc/grpc:1.30.0' 'google/protobuf:3.13.*'
  • install grpc extension

usage

instantiate a client

grpc
// connect to the server using grpc
$phprom = new PHProm('127.0.0.1:3333');
// or
$phprom = new PHProm('127.0.0.1:3333', PHProm::GRPC_API);
rest/http
// or connect to the server using rest/http
$phprom = new PHProm('127.0.0.1:3333', PHProm::REST_API);

!NOTE! see the suggested packages list in composer.json:

  "suggest": {
    "ext-grpc": "* required for grpc api",
    "ext-curl": "* required for rest/http api"
  }
grpc vs rest/http

both the grpc and rest/http api benchmark at about the same when running on a local network:

  • min: 2ms
  • max: 12ms
  • avg: ~6ms

get the metrics for the prometheus scraper

print($phprom->get());
// or...
echo $phprom->get();

register and record metrics automagically

counter
$counter = (new Counter($phprom))
    ->setNamespace('namespace')
    ->setName('name')
    ->setDescription('description')
    ->setLabels(['label1', 'label2']); //<< optional

$counter->record(
    1.2345, 
    ['label1' => 'foo', 'label2' => 'bar']
);
histogram
$histogram = (new Histogram($phprom))
    ->setNamespace('namespace')
    ->setName('name')
    ->setDescription('description')
    ->setLabels(['label1', 'label2']) //<< optional
    ->setBuckets([0.1, 0.5, 1, 2, 5]); //<< optional

$histogram->record(
    1.2345, 
    ['label1' => 'foo', 'label2' => 'bar']
);
summary
$summary = (new Summary($phprom))
    ->setNamespace('namespace')
    ->setName('name')
    ->setDescription('description')
    ->setLabels(['label1', 'label2']) //<< optional
    ->setObjectives([0.1, 0.5, 1, 2, 5]) //<< optional
    ->setMaxAge(0) //<< optional
    ->setAgeBuckets(0) //<< optional
    ->setBufCap(0); //<< optional

$summary->record(
    1.2345, 
    ['label1' => 'foo', 'label2' => 'bar']
);
gauge
$gauge = (new Gauge($phprom))
    ->setNamespace('namespace')
    ->setName('name')
    ->setDescription('description')
    ->setLabels(['label1', 'label2']); //<< optional

$gauge->record(
    1.2345, 
    ['label1' => 'foo', 'label2' => 'bar']
);

create a timer to time and record latencies

$histogram = (new Histogram($phprom))
    ->setNamespace('namespace')
    ->setName('name')
    ->setDescription('description')
    ->setLabels(['label1', 'label2'])
    ->setBuckets(range(1, 10));

$timer = new Timer($histogram);

$timer->start();

sleep(rand(1, 10));

$timer->stop()
    ->record(['label1' => 'foo', 'label2' => 'bar'])
    ->reset();

register and record metrics manually

counter
$phprom->registerCounter(
    'namespace',
    'name',
    'description',
    ['label1', 'label2'] //<< optional
);

$phprom->recordCounter(
    'namespace',
    'name',
    1.2345,
    ['label1' => 'foo', 'label2' => 'bar']
);
histogram
$phprom->registerHistogram(
    'namespace',
    'name',
    'description',
    ['label1', 'label2'], //<< optional
    [0.1, 0.5, 1, 2, 5] //<< custom buckets, optional
);

$phprom->recordHistogram(
    'namespace',
    'name',
    1.2345,
    ['label1' => 'foo', 'label2' => 'bar']
);
summary
$phprom->registerSummary(
    'namespace',
    'name',
    'description',
    ['label1', 'label2'], //<< optional
    [0.1, 0.5, 1, 2, 5], //<< objectives, optional
    0, //<< max age, optional
    0, //<< age buckets, optional
    0 //<< buf cap, optional
);

$phprom->recordSummary(
    'namespace',
    'name',
    1.2345,
    ['label1' => 'foo', 'label2' => 'bar']
);
gauge
$phprom->registerGauge(
    'namespace',
    'name',
    'description',
    ['label1', 'label2'] //<< optional
);

$phprom->recordGauge(
    'namespace',
    'name',
    1.2345,
    ['label1' => 'foo', 'label2' => 'bar']
);