joeri-abbo/laravel-prometheus-exporter

Laravel 的 Prometheus 导出器

维护者

详细信息

github.com/Joeri-Abbo/laravel-prometheus-exporter

源代码

问题

安装: 258

依赖项: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 1

开放问题: 1

1.0.1 2023-08-16 08:00 UTC

Requires

Requires (Dev)

MIT f095f92ae3e9a0e3d5c49d64bc9b4efbc0b2cc3a

  • Joeri Abbo <joeri.woop@tracefy.com>

This package is auto-updated.

Last update: 2024-09-09 22:08:56 UTC

README

为 Laravel 提供的 Prometheus 导出器包。

简介

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

此包是一个包装器，将 jimdo/prometheus_client_php 包装进 Laravel 和 Lumen。

安装

使用 composer 安装包

composer require joeri-abbo/laravel-prometheus-exporter

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

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

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

$app->register(JoeriAbbo\LaravelPrometheusExporter\PrometheusServiceProvider::class);

有关在应用程序路由、Guzzle 调用和 SQL 查询上启用指标的操作指南，请参阅下面

配置

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

PROMETHEUS_NAMESPACE=app

PROMETHEUS_METRICS_ROUTE_ENABLED=true
PROMETHEUS_METRICS_ROUTE_PATH=metrics
PROMETHEUS_METRICS_ROUTE_MIDDLEWARE=null
PROMETHEUS_COLLECT_FULL_SQL_QUERY=true
PROMETHEUS_STORAGE_ADAPTER=memory

PROMETHEUS_REDIS_HOST=localhost
PROMETHEUS_REDIS_PORT=6379
PROMETHEUS_REDIS_TIMEOUT=0.1
PROMETHEUS_REDIS_READ_TIMEOUT=10
PROMETHEUS_REDIS_PERSISTENT_CONNECTIONS=0
PROMETHEUS_REDIS_PREFIX=PROMETHEUS_

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

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

指标

该包允许您观察以下指标

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

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

$app->middleware([
    JoeriAbbo\LaravelPrometheusExporter\RouteMiddleware::class,
]);

导出的标签是

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

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

$app->register(JoeriAbbo\LaravelPrometheusExporter\GuzzleServiceProvider::class);

导出的标签是

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

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

$app->register(JoeriAbbo\LaravelPrometheusExporter\DatabaseServiceProvider::class);

导出的标签是

[
    'query',
    'query_type',
]

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

存储适配器

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

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

使用 PROMETHEUS_STORAGE_ADAPTER 环境变量来指定存储适配器。

如果使用 redis，还需要配置 PROMETHEUS_REDIS_HOST 和 PROMETHEUS_REDIS_PORT 变量。可选地，您还可以更改 PROMETHEUS_REDIS_TIMEOUT、PROMETHEUS_REDIS_READ_TIMEOUT 和 PROMETHEUS_REDIS_PERSISTENT_CONNECTIONS 变量。

导出指标

该包添加了一个默认启用的 /metrics 端点，该端点公开了收集器收集的所有指标。

可以使用 PROMETHEUS_METRICS_ROUTE_ENABLED 环境变量打开/关闭此功能，也可以使用 PROMETHEUS_METRICS_ROUTE_PATH 环境变量进行更改。

收集器

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

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

示例

使用示例

这是 Lumen 应用程序的示例使用方法

// retrieve the exporter (you can also use app('prometheus') or Prometheus::getFacadeRoot())
$exporter = app(\JoeriAbbo\LaravelPrometheusExporter\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 JoeriAbbo\LaravelPrometheusExporter;

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']);
    }
}