README

在您的项目根目录中运行以下命令。

$ composer require dbstudios/prometheus-client

入门指南

为了开始使用这个库，您需要设置两个组件。第一个是 CollectorRegistry，它充当收集器的仓库。您无需进行任何特殊配置，只需一个可以在应用程序的任何地方访问的实例即可。

<?php
    use DaybreakStudios\PrometheusClient\CollectorRegistry;
    
    $registry = new CollectorRegistry();

接下来是一个适配器，它充当库代码与您选择的存储系统之间的接口。在编写本文时，此库包含以下适配器的支持。

Redis
文件系统
APCu

实例化将因适配器而异，请查看您使用的适配器的文档。

<?php
    use DaybreakStudios\PrometheusClient\Adapter\Apcu\ApcuAdapter;
    
    $adapter = new ApcuAdapter();

最后，您需要一个或多个收集器。

<?php
    use DaybreakStudios\PrometheusClient\Collector\Counter;
    use DaybreakStudios\PrometheusClient\Collector\Gauge;
    use DaybreakStudios\PrometheusClient\Collector\Histogram;
    
    $counter = new Counter($adapter, 'test_counter', 'Please ignore');
    $registry->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);

一旦注册了收集器，您可以通过全局变量或通过 CollectorRegistry（需要以某种方式全局访问）通过名称暴露它们。

<?php
    $testCounter = $registry->get('test_counter');
    $testCounter->increment();
    
    $testHistogram = $registry->get('test_histogram');
    $testHistogram->observe(153);

强类型

为了在从注册表中检索收集器时强制执行类型，您可以使用 getCounter()、getGauge() 和 getHistogram() 方法来替换基本的 get() 方法。

<?php
    $counter = $registry->getCounter('test_counter');
    $counter->increment();
    
    $histogram = $registry->getHistogram('test_gauge');
    // throws DaybreakStudios\PrometheusClient\Exception\CollectorRegistryException due to type mismatch

除了执行与 get() 相同的 null 检查之外，这些方法中的每一个还将检查收集器是否为预期的类型，并在收集器不是预期的类型时抛出异常。由于这三个方法在它们的 PHPDoc 块中指定了正确的返回类型，因此它们还将正确启用 IDE 自动完成。

使用标签

在注册收集器时，必须定义收集器的所有标签。

<?php
    use DaybreakStudios\PrometheusClient\Collector\Counter;
    
    $counter = new Counter($adapter, 'api_calls_total', 'Number of API calls made', [
        'path',
        'method',  	
    ]);
    
    $counter->increment([
    	'method' => 'GET',
    	'path' => '/users/me',
    ]);

您指定标签的顺序（即在上面的示例中 Counter::increment() 中的使用）并不重要，但是每次必须提供所有标签值。

导出

您可以通过在应用程序中设置与以下代码类似的端点来从您的注册表中导出数据。

<?php
    use DaybreakStudios\PrometheusClient\Export\Render\TextRenderer;
    
    $renderer = new TextRenderer();
    
    header('Content-Type: ' . $renderer->getMimeType());
    echo $renderer->render($registry->collect());

收集器

收集器是您的代码与 Prometheus 之间的接口。Prometheus 规范目前定义了 3 种支持的收集器类型，如下所述。

有关收集器概念的更多信息，请参阅官方 Prometheus 文档。

计数器

计数器是收集器的最简单形式。官方 Prometheus 文档如此描述计数器。

计数器 是一个累积指标，它表示一个单一的单调递增计数器，其值只能增加或重启时重置为零。

基本上，计数器是只能增加的收集器，通常以 1 的增量。例如，您可能用它来跟踪应用程序服务的请求数量，或者应用程序执行的数据库查询数量。

<?php
    use DaybreakStudios\PrometheusClient\Collector\Counter;

    /**
     * @var \DaybreakStudios\PrometheusClient\Adapter\AdapterInterface $adapter 
     */
    $counter = new Counter($adapter, 'requests_served', 'The number of requests processed by the application');

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

Counter::increment() 的所有参数都是可选的。第一个参数是用于要增加的计数器的标签。第二个参数是增加的步长（默认为 1）。

仪表

仪表与计数器非常相似。计数器不同之处在于，它们可以增加或减少，甚至可以将当前值设置为特定数字。Prometheus官方文档这样描述仪表。

仪表是一种表示可以任意上升和下降的单个数值的度量。

仪表可以用来跟踪温度、CPU或内存使用情况等。

<?php
    use DaybreakStudios\PrometheusClient\Collector\Gauge;

    /**
     * @var \DaybreakStudios\PrometheusClient\Adapter\AdapterInterface $adapter
     */
    $gauge = new Gauge($adapter, 'cpu_usage_last5', 'CPU usage average over the last 5 minutes');

    $gauge->increment();
    $gauge->decrement();
    $gauge->set(1.7);

与计数器类似，Gauge::increment()和Gauge::decrement()的参数是可选的。两者都接受最多两个参数：标签和步长，顺序如下。

您可以使用Gauge::set()将仪表更新为特定值。它接受一个或两个参数，第一个是设置仪表所需值，第二个是可选的仪表标签。

直方图

与计数器和仪表相比，直方图是一个相对复杂的收集器。Prometheus官方文档这样描述直方图。

直方图对观察值（通常是请求持续时间或响应大小）进行采样，并在可配置的桶中进行计数。它还提供了所有观察值的总和。

当您处理的度量可能每次记录时都会大幅变化时，直方图很有用。它可以用来将记录的度量分离成分位数，以便更容易分析。例如，直方图可以用来分析不同代码路径的执行时间，并以一种可以轻松识别异常值的方式记录数据（例如，有一段特别慢的代码，无论您投入多少个小时都无法使其运行得更快）。

<?php
    use DaybreakStudios\PrometheusClient\Collector\Histogram;
   
    /**
     * @var \DaybreakStudios\PrometheusClient\Adapter\AdapterInterface $adapter
     */
    $histogram = new Histogram(
        $adapter,
        'api_call_execution_time_milliseconds',
        'Call time to external API',
        [50, 1000, 5000]
    );

    $histogram->observe(17);
    $histogram->observe(120);
    $histogram->observe(2700);
    $histogram->observe(7010);

由于直方图通常用于计时，因此有两个内置的实用方法用于处理时间。请注意，您需要安装symfony/stopwatch组件才能使用计时功能。

<?php
    /**
     * @var \DaybreakStudios\PrometheusClient\Collector\Histogram $histogram
     */

    $timer = $histogram->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

默认情况下，直方图以毫秒精度跟踪时间。但是，直方图接受一个可选的构造函数参数，以将此更改为秒精度，如果这更适合您的需求。

<?php
    use DaybreakStudios\PrometheusClient\Collector\Histogram;
    use DaybreakStudios\PrometheusClient\Collector\HistogramTimer;

    /**
     * @var \DaybreakStudios\PrometheusClient\Adapter\AdapterInterface $adapter
     */
    $histogram = new Histogram(
        $adapter,
        'api_call_execution_time_seconds',
        'Call time to external API',
        [100, 1000, 5000],
        [],
        HistogramTimer::PRECISION_SECONDS,
    );

    $histogram->time(function() {
        usleep(1100000); // ~1100 ms or 1.1 s
    }); // Adds 1 to the histogram (e.g. `$histogram->observe(1)`)

适配器

此库通过适配器提供对底层存储系统的访问。下面的文档描述了内置的适配器。

Redis

DaybreakStudios\PrometheusClient\Adapter\Redis\RedisAdapter使用Redis存储度量。要使用Redis适配器，您只需提供Redis实例的主机即可。

<?php
    use DaybreakStudios\PrometheusClient\Adapter\Redis\RedisAdapter;
    use DaybreakStudios\PrometheusClient\Adapter\Redis\RedisClientConfiguration;

    $config = new RedisClientConfiguration('localhost');
    
    // You can also supply other information, such as port or password, using the setters
    // available on the configuration object, e.g.:
    //     - $config->setPort(1234)
    //     - $config->setPassword('MyTotallySecurePassword')

    $adapter = new RedisAdapter($config);

Redis适配器中的键会自动添加前缀，以防止与Redis实例中可能存在的其他键冲突。默认前缀是"dbstudios_prom:"，但您可以通过向RedisClientConfiguration的构造函数提供第二个参数来更改此前缀。

文件系统

DaybreakStudios\PrometheusClient\Adapter\Filesystem\FilesystemAdapter使用文件存储度量。适配器写入文件的数据使用PHP的serialize()函数进行编码，因此类型将被正确保留。要使用FilesystemAdapter，您需要指定适配器应使用的目录以存储其文件。为了防止数据丢失，您指定的目录应仅用于Prometheus。

<?php
    use DaybreakStudios\PrometheusClient\Adapter\Filesystem\FilesystemAdapter;
    
    $adapter = new FilesystemAdapter('/var/www/html/prometheus');

与APCu适配器不同，缓存的数据将持久化，即使您的服务器重新启动也是如此。您可以使用FilesystemAdapter::clear()方法从适配器的缓存中删除所有文件。请注意，这将删除您指定的适配器基本目录中的所有内容。

APCu

DaybreakStudios\PrometheusClient\Adapter\Apcu\ApcuAdapter使用APCu存储度量。APCu适配器不需要任何额外的配置。

然而，有一些陷阱需要注意。APCu默认情况下，不会在特定事件中持久化存储的数据，例如服务器重启。此外，当缓存填满时，它还会清除整个缓存。这些都不会对你的Prometheus安装造成问题，但如果你选择使用APCu适配器，这是你应该记住的。

此外，APCu 不支持 正确访问从命令行启动的PHP会话的缓存。在默认配置下，对apcu_*函数的每次调用都会被“黑洞”，这意味着它们总是返回false，并且不会在缓存中存储任何数据。你可以通过在php.ini中添加apc.enable_cli=1来启用CLI缓存，但这只会让信息在脚本运行时保持在缓存中。一旦脚本执行完毕，缓存数据将被清除。据我所知，无法更改这种行为。

dbstudios / prometheus-client

维护者

详细信息