Utopia Telemetry

Important

This repository is a read-only mirror of the utopia-php monorepo. Development happens in packages/telemetry — please open issues and pull requests there.

Utopia Telemetry is a powerful telemetry library. This library is aiming to be as simple and easy to learn and use. This library is maintained by the Appwrite team.

Although this library is part of the Utopia System project it is dependency free and can be used as standalone with any other PHP project or framework.

Getting started

Install using Composer:

composer require utopia-php/telemetry

Init in your application:

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Utopia\Telemetry\Adapter\OpenTelemetry;

$telemetry = new OpenTelemetry('http://localhost:4318/v1/metrics', 'namespace', 'app', 'unique-instance-id');

// Periodically collect and export metrics to the configured OpenTelemetry endpoint.
$telemetry->collect();

// Example using Swoole
\Swoole\Timer::tick(60_000, fn () => $telemetry->collect());

Metric types

Create instruments wherever it suits your code, including at boot: an instrument reaches the exporter only once it has been written to. An instrument that never records exports nothing, so it cannot produce a metric with zero data points — which Prometheus 3.13 and later rejects, taking the rest of the OTLP request with it.

Counter

A monotonically increasing counter. Only positive increments are allowed.

$counter = $telemetry->createCounter('http.server.requests', '{request}', 'Total HTTP requests');

$counter->add(1);
$counter->add(1, ['method' => 'GET', 'status' => '200']);

UpDownCounter

A counter that can increase or decrease. Useful for tracking values like active connections.

$upDownCounter = $telemetry->createUpDownCounter('http.server.active_requests', '{request}', 'Active HTTP requests');

$upDownCounter->add(1);   // request started
$upDownCounter->add(-1);  // request finished

Histogram

Records a distribution of values. Useful for measuring latency or payload sizes.

$histogram = $telemetry->createHistogram('http.server.request.duration', 'ms', 'HTTP request duration');

$histogram->record(142);
$histogram->record(98.5, ['route' => '/api/users']);

Gauge

Records an instantaneous measurement. Useful for values that can arbitrarily go up or down.

$gauge = $telemetry->createGauge('system.memory.usage', 'By', 'Memory usage');

$gauge->record(1_073_741_824);
$gauge->record(536_870_912, ['host' => 'server-1']);

ObservableGauge

An asynchronous gauge whose value is collected via a callback at export time. Useful for values that are expensive to compute or come from an external source (e.g. CPU usage, queue depth).

$observableGauge = $telemetry->createObservableGauge('process.cpu.usage', '%', 'CPU usage');

$observableGauge->observe(function (callable $observer): void {
    // This callback is invoked each time metrics are collected.
    $observer(sys_getloadavg()[0] * 100);
    $observer(72.4, ['core' => '0']);
    $observer(68.1, ['core' => '1']);
});

System requirements

Utopia Framework requires PHP 8.0 or later. We recommend using the latest PHP version whenever possible.

Copyright and license

The MIT License (MIT) http://www.opensource.org/licenses/mit-license.php