README

为Lumen和Laravel提供Prometheus导出器的包。

简介

Prometheus是一个具有UI和复杂的查询语言（PromQL）的时间序列数据库，可以通过HTTP抓取指标、计数器、仪表和直方图。

此包是一个包装器，用于将beatlabs/prometheus_client_php（jimdo/prometheus_client_php的分支）桥接到Lumen和Laravel。

示例

前往examples/lumen-app查看我们的示例应用程序。要获取它，您需要克隆Pyr存储库，因为从composer下载时示例不包括在内。

示例是一个完整的项目，包含自己的README.md，因此您可以检查库的功能以及它打算如何使用。

安装

将存储库添加到composer.json

"repositories": [
  {
    "type": "vcs",
    "url": "https://github.com/beatlabs/pyr"
  }
],

通过composer安装此包

composer require beatlabs/pyr

然后，您可以在应用程序的bootstrap/app.php中启用外观并注册外观

$userAliases = [
    // ...
    Beat\Pyr\PrometheusFacade::class => 'Prometheus',
];
$app->withFacades(true, $userAliases);

然后您应该在bootstrap/app.php中注册服务提供者

$app->register(Beat\Pyr\PrometheusServiceProvider::class);

有关如何在应用程序路由、Guzzle调用和SQL查询上启用指标的说明，请参阅以下内容

配置

该包有一个默认配置，使用以下环境变量。

PYR_NAMESPACE=app

PYR_METRICS_ROUTE_ENABLED=true
PYR_METRICS_ROUTE_PATH=metrics
PYR_METRICS_ROUTE_MIDDLEWARE=null
PYR_COLLECT_FULL_SQL_QUERY=true
PYR_STORAGE_ADAPTER=memory

PYR_REDIS_HOST=localhost
PYR_REDIS_PORT=6379
PYR_REDIS_TIMEOUT=0.1
PYR_REDIS_READ_TIMEOUT=10
PYR_REDIS_PERSISTENT_CONNECTIONS=0
PYR_REDIS_PREFIX=PYR_

要自定义配置值，您可以通过覆盖上述环境变量（通常在应用程序的.env文件中完成此操作）或复制包含的prometheus.php到config/prometheus.php来编辑它，并按以下方式在应用程序中使用它

$app->loadComponent('prometheus', [
    Beat\Pyr\PrometheusServiceProvider::class
]);

指标

该包允许您观察以下指标

• 应用程序路由。请求方法、请求路径和状态码的指标。
• Guzzle调用。请求方法、URI和状态码的指标。
• SQL查询。SQL查询和查询类型的指标。

为了在应用程序路由中观察指标（请求和响应之间的时间），您应该在应用程序的bootstrap/app.php中注册以下中间件

$app->middleware([
    Beat\Pyr\RouteMiddleware::class,
]);

导出的标签是

[
    'method',
    'route',
    'status_code',
]

为了观察Guzzle指标，您应该在bootstrap/app.php中注册以下提供者

$app->register(Beat\Pyr\GuzzleServiceProvider::class);

导出的标签是

[
    'method',
    'external_endpoint',
    'status_code'
]

为了观察SQL指标，您应该在bootstrap/app.php中注册以下提供者

$app->register(Beat\Pyr\DatabaseServiceProvider::class);

导出的标签是

[
    'query',
    'query_type',
]

注意：您可以通过禁用PYR_COLLECT_FULL_SQL_QUERY的配置来禁用记录完整查询。

存储适配器

存储适配器用于在请求之间持久化指标。默认情况下启用memory适配器，这意味着数据仅在当前请求中持久化。

我们建议在生产环境中使用redis或apc适配器。当然，您的安装必须提供Redis或APC实现。

PYR_STORAGE_ADAPTER环境变量用于指定存储适配器。

如果使用redis，则需要配置PYR_REDIS_HOST和PYR_REDIS_PORT变量。可选地，您可以更改PYR_REDIS_TIMEOUT、PYR_REDIS_READ_TIMEOUT和PYR_REDIS_PERSISTENT_CONNECTIONS变量。

导出指标

该软件包添加了一个默认启用的 /metrics 端点，用于暴露由收集器收集的所有指标。

可以通过使用环境变量 PYR_METRICS_ROUTE_ENABLED 来开启或关闭，也可以使用环境变量 PYR_METRICS_ROUTE_PATH 来修改。

收集器

收集器是一个类，实现了 CollectorInterface 接口，负责收集一个或多个指标的数值。

请参阅下方的 示例。

您可以通过将收集器添加到 prometheus.php 配置文件中的 collectors 数组来自动加载您的收集器。

示例

示例用法

以下是一个Lumen应用程序的示例用法

// retrieve the exporter (you can also use app('prometheus') or Prometheus::getFacadeRoot())
$exporter = app(\Beat\Pyr\PrometheusExporter::class);

// register a new collector
$collector = new \My\New\Collector();
$exporter->registerCollector($collector);

// retrieve all collectors
var_dump($exporter->getCollectors());

// retrieve a collector by name
$collector = $exporter->getCollector('user');

// export all metrics
// this is called automatically when the /metrics end-point is hit
var_dump($exporter->export());

// the following methods can be used to create and interact with counters, gauges and histograms directly
// these methods will typically be called by collectors, but can be used to register any custom metrics directly,
// without the need of a collector

// create a counter
$counter = $exporter->registerCounter('search_requests_total', 'The total number of search requests.');
$counter->inc(); // increment by 1
$counter->incBy(2);

// create a counter (with labels)
$counter = $exporter->registerCounter('search_requests_total', 'The total number of search requests.', ['request_type']);
$counter->inc(['GET']); // increment by 1
$counter->incBy(2, ['GET']);

// retrieve a counter
$counter = $exporter->getCounter('search_requests_total');

// create a gauge
$gauge = $exporter->registerGauge('users_online_total', 'The total number of users online.');
$gauge->inc(); // increment by 1
$gauge->incBy(2);
$gauge->dec(); // decrement by 1
$gauge->decBy(2);
$gauge->set(36);

// create a gauge (with labels)
$gauge = $exporter->registerGauge('users_online_total', 'The total number of users online.', ['group']);
$gauge->inc(['staff']); // increment by 1
$gauge->incBy(2, ['staff']);
$gauge->dec(['staff']); // decrement by 1
$gauge->decBy(2, ['staff']);
$gauge->set(36, ['staff']);

// retrieve a gauge
$counter = $exporter->getGauge('users_online_total');

// create a histogram
$histogram = $exporter->registerHistogram(
    'response_time_seconds',
    'The response time of a request.',
    [],
    [0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]
);
// the buckets must be in asc order
// if buckets aren't specified, the default 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0 buckets will be used
$histogram->observe(5.0);

// create a histogram (with labels)
$histogram = $exporter->registerHistogram(
    'response_time_seconds',
    'The response time of a request.',
    ['request_type'],
    [0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]
);
// the buckets must be in asc order
// if buckets aren't specified, the default 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0 buckets will be used
$histogram->observe(5.0, ['GET']);

// retrieve a histogram
$counter = $exporter->getHistogram('response_time_seconds');

收集器

以下是一个示例收集器实现

<?php

declare(strict_types = 1);

namespace Beat\Pyr;

use Prometheus\Gauge;

class ExampleCollector implements CollectorInterface
{
    /**
     * @var Gauge
     */
    protected $usersRegisteredGauge;

    /**
     * Return the name of the collector.
     *
     * @return string
     */
    public function getName() : string
    {
        return 'users';
    }

    /**
     * Register all metrics associated with the collector.
     *
     * The metrics needs to be registered on the exporter object.
     * eg:
     * ```php
     * $exporter->registerCounter('search_requests_total', 'The total number of search requests.');
     * ```
     *
     * @param PrometheusExporter $exporter
     */
    public function registerMetrics(PrometheusExporter $exporter) : void
    {
        $this->usersRegisteredGauge = $exporter->registerGauge(
            'users_registered_total',
            'The total number of registered users.',
            ['group']
        );
    }

    /**
     * Collect metrics data, if need be, before exporting.
     *
     * As an example, this may be used to perform time consuming database queries and set the value of a counter
     * or gauge.
     */
    public function collect() : void
    {
        // retrieve the total number of staff users registered
        // eg: $totalUsers = Users::where('group', 'staff')->count();
        $this->usersRegisteredGauge->set(36, ['staff']);

        // retrieve the total number of regular users registered
        // eg: $totalUsers = Users::where('group', 'regular')->count();
        $this->usersRegisteredGauge->set(192, ['regular']);
    }
}