README

Neos Flow / PHP的Prometheus客户端库

此Flow包允许您收集和提供指标给Prometheus。它支持客户端聚合指标数据，并为Prometheus提供了一个端点以抓取这些指标。

它是如何工作的？

您的Flow应用程序可以提供不同类型的指标，例如当前注册用户数量（一个量规），或对您的API的请求数量（一个计数器）。指标值存储在存储中——目前只支持Redis，还有一个内存存储用于测试。

指标端点（默认为http(s)://your-host/metrics）从存储中收集所有当前指标值，并以Prometheus可以读取的格式渲染。因此，在向指标端点发送请求时不会收集或生成指标。根据更新指标的成本（例如：传入的HTTP请求数量与过去15年售出但退货的书籍数量相比），值可能会实时更新（例如，通过注册Flow HTTP组件）或通过辅助进程（cron作业或长时间运行的命令行进程）。

兼容性

0.*版本的flownative/prometheus分支支持Flow 5.x和6.x，而1.*版本的flownative/prometheus支持Flow 7.0及以后版本。请注意，此README适用于1.*。[参阅"0"分支的README](https://github.com/flownative/flow-prometheus/blob/0/README.md ，如果您正在使用此插件的早期版本）。

安装

通过Composer将Prometheus集成作为常规Flow包安装。对于您的现有项目，只需将flownative/prometheus包含到Flow或Neos分发的依赖中

$ composer require flownative/prometheus

存储

默认情况下，此插件使用InMemoryStorage进行测试目的。您希望使用RedisStorage，这样就不会在请求之间丢失所有指标值。此包中包含的RedisStorage不需要特殊的PHP扩展，因为它是用纯PHP实现的。

要使用RedisStorage，在您的包或Flow分发的Configuration目录中创建一个Objects.yaml文件，并添加以下配置

Flownative\Prometheus\DefaultCollectorRegistry:
  arguments:
    1:
      object: Flownative\Prometheus\Storage\RedisStorage

Flownative\Prometheus\Storage\RedisStorage:
  arguments:
    1:
      value:
        hostname: '%env:MY_REDIS_HOST%'
        port: '%env:MY_REDIS_PORT%'
        password: '%env:MY_REDIS_PASSWORD%'
        database: 20

在此示例中，使用环境变量将访问参数传递给RedisStorage。通过在浏览器中打开Flow实例的路径/metrics来测试您的设置。您应该看到以下注释

# Flownative Prometheus Metrics Exporter: There are no collectors registered at the registry.

RedisStorage还支持具有Sentinel服务器的Redis集群设置。如果您想连接到集群并使用Sentinels进行自动发现，请省略主机名和密码选项，并使用sentinel选项

Flownative\Prometheus\Storage\RedisStorage:
  arguments:
    1:
      value:
        password: '%env:MY_REDIS_PASSWORD%'
        database: 20
        sentinels:
          - 'tcp://10.101.213.145:26379'
          - 'tcp://10.101.213.146:26379'
          - 'tcp://10.101.213.147:26379'
        service: 'mymaster'

您还可以将Sentinels作为逗号分隔的字符串设置。

RedisStorage可以配置为忽略连接错误。这可能会在Redis不可用时保护您的应用程序免受致命错误的影响。当然，当Redis连接失败时不会存储指标。

Flownative\Prometheus\Storage\RedisStorage:
  arguments:
    1:
      value:
        hostname: '%env:MY_REDIS_HOST%'
        port: '%env:MY_REDIS_PORT%'
        password: '%env:MY_REDIS_PASSWORD%'
        database: 20
        ignoreConnectionErrors: true

遥测路径

默认情况下，提供抓取指标的路径为“/metrics”。您可以通过在Objects.yaml中设置HTTP中间件的相应选项来更改此路径。

Flownative\Prometheus\Http\MetricsExporterMiddleware:
  arguments:
    1:
      value:
        ## Path at which metrics are published for scraping
        telemetryPath: '/some-other-path'

安全

默认情况下，遥测端点不启用。当环境变量FLOWNATIVE_PROMETHEUS_ENABLE设置为“true”（即“true”是一个字符串值）时，它将启用。您可以通过在您的Web服务器虚拟主机配置中设置该变量来实现这一点。

通过这种变量启用遥测背后的想法是，您可以将您的Web服务器配置为通过不同于您的实际网站或应用的端口提供指标。这样，您可以通过防火墙规则或通过您的负载均衡器不提供对该端口的访问来轻松隐藏指标。

在为专用端口设置遥测端点时，也可以让它与Web服务器的端口共享。

遥测端点还可以通过要求客户端首先使用用户名和密码进行身份验证来保护。HTTP基本身份验证的配置如下（Objects.yaml）

Flownative\Prometheus\Http\MetricsExporterMiddleware:
  arguments:
    1:
      value:
        basicAuth:

          # If set to non-empty values, HTTP Basic Auth is enabled:
          username: 'my-username'
          password: 'my-password'
    
          # Optional:
          realm: 'Acme App Metrics'

用法

DefaultCollectorRegistry已预配置，可以通过依赖注入进行注入

    /**
     * @Flow\Inject
     * @var \Flownative\Prometheus\CollectorRegistry\DefaultCollectorRegistry
     */
    protected $collectorRegistry;

一个简单的计数器

    $this->collectorRegistry->getCounter('acme_myproject_controller_hits_total')
        ->inc();   

使用标签的计数器

    $this->collectorRegistry->getCounter('acme_myproject_controller_hits_total')
        ->inc(1, ['result' => 'success']);   
    …
    $this->collectorRegistry->getCounter('acme_myproject_controller_hits_total')
        ->inc(1, ['result' => 'failed']);   

仪表

    $this->collectorRegistry->getGauge('neos_flow_sessions')
        ->set(count($this->sessionManager->getActiveSessions()),
            [
                'state' => 'active'
            ]
        );

每个指标的设置

Flownative:
  Prometheus:
    metrics:
      acme_myproject_controller_hits_total:
        type: counter
        help: 'metric description'
      acme_myproject_successful_login_total:
        type: counter
        help: 'metric description'

使用InMemoryStorage手动使用Collector Registry

    $registry = new CollectorRegistry(new InMemoryStorage());
    $registry->register('flownative_prometheus_test_calls_total', Counter::TYPE, 'a test call counter', ['tests', 'counter']);

    $counter = $registry->getCounter('flownative_prometheus_test_calls_total');
    $counter->inc(5.5);

    $sampleCollections = $registry->collect();

    $renderer = new Renderer();
    echo ($renderer->render($sampleCollections));

运行测试

所有关键功能都由单元测试支持。目前，您需要运行Redis才能运行它们。请通过REDIS_HOST、REDIS_PORT和REDIS_PASSWORD提供必要的凭据（请参阅包含在此包中的Objects.yaml）。

除此之外，测试的运行方式与Flow的其他单元测试套件一样。