README

PHPProm 是一个用于测量一些与性能相关的指标并将它们暴露给 Prometheus 的库。

其目标是提供一种简单、即插即用的解决方案来开始测量，但又不限制自定义。

由于 Prometheus 定期通过访问特定端点收集度量，因此需要存储它们。PHPProm 提供了对 Redis 或 Memcached 等各种后端的支持。

文档

API 文档 0.1.0

包

PHPProm 使用 SemVer 进行版本控制。由于版本小于 1.0.0，API 变化很快，因此升级时请注意变更日志中的说明。

稳定版

"require": {
    "philiplb/phpprom": "0.1.0"
}

尖端版

"require": {
    "philiplb/phpprom": "0.2.x-dev"
}

入门指南

以下是一个示例，说明如何快速开始测量使用 Redis 作为存储的 Silex 应用程序

先决条件

您需要安装 PHP redis 扩展。

您还需要有一个正在运行的 Redis 服务器。在这里，我们假设 "localhost" 作为主机，"supersecret" 作为认证密码。

需要 PHPProm

PHPProm 包通过 composer 集成

composer require "philiplb/phpprom"

设置 Silex 应用程序

第一步是创建一个存储对象

$storage = new PHPProm\Storage\Redis('localhost', 'supersecret');

有了这个，就可以调用 Silex 设置。它返回一个用作指标路由的函数，该路由可以被 Prometheus 抓取

$silexPrometheusSetup = new PHPProm\Integration\SilexSetup();
$metricsAction = $silexPrometheusSetup->setupAndGetMetricsRoute($app, $storage);
$app->get('/metrics', $metricsAction);

集成

将一些 Prometheus 可抓取的指标集成应该尽可能简单。因此，将框架的一些设置步骤抽象为集成，以便使 PHPProm 成为一种即插即用的解决方案。

将提供更多集成。如果您有特定的请求，请给我留言。或者发起一个 pull request。 :)

Silex

Silex 集成测量以下指标

每个路由花费的时间作为仪表
每个路由消耗的内存作为仪表
每个路由被调用的频率作为计数器

每个指标都有路由作为标签 "name"。而斜杠被替换为下划线，并且路由方法被添加前缀。因此，像这样的路由

$app->get('my/great/{route}', function($route) {
	// ...
});

获取标签 "GET_my_great_{route}"。

此集成需要包 "silex/silex"。

它由类 PHPProm\Integration\SilexSetup 表示，其用法在 "入门指南" 部分中解释。

通过存储实例的 addAvailableMetric 函数轻松添加更多指标。有关自定义集成的详细说明，请参阅子章节。

实际度量通过相应的存储实例函数添加（请再次参阅自定义集成子章节）。所有数据都自动出现在指标端点中。

自定义集成

编写自定义集成由三个部分组成。首先，必须将要测量的指标添加到存储实例中，然后进行测量，最后提供一个 Prometheus 可抓取的指标端点。

首先，必须通过 addAvailableMetric 方法将指标添加到存储实例中

$storage->addAvailableMetric(
	$metric, // the Prometheus metric name itself
	$label, // the name of the one Prometheus label to categorize the values
	$help, // a small, meaningful help text for the metric
	$type, // the Prometheus type of the metric like "gauge" or "counter"
	$defaultValue // the default value to be taken if no measurement happened yet for the metric/label combination, "Nan" for example or "0"
);

现在，必须进行测量。存储对象提供了两种方法来完成此操作

storeMeasurement($metric, $key, $value): 在给定的键下存储一个指标的原始值
incrementMeasurement($metric, $key): 根据给定键增加指标的计数器，如果之前不存在则从1开始

存在一个用于测量时间的辅助类 PHPProm\StopWatch。要开始测量，调用其函数 start()，要停止并存储测量结果，调用函数 stop($metric, $key)。参数的含义与存储函数的参数相同。

第三部分是提供交付指标的端点。要获取内容，存在类 PHPProm\PrometheusExport。它有一个公共函数 getExport(AbstractStorage $storage, $keys)，其中传入存储实例以及所有预期的键。该函数返回一个包含所有Prometheus数据的字符串，用作端点的响应。它应与 "Content-Type: text/plain; version=0.0.4" 一起交付。

存储实现

对于测量，有几种存储实现可供使用，以便指标端点可以交付它们。如果现有的实现不涵盖用例，也容易编写自己的实现。它们都在命名空间 PHPProm\Storage 中。

Redis

Redis存储需要安装PHP redis 扩展。其构造函数接受以下参数

string $host: 连接主机
null|string $password: 用于认证的密码，null表示忽略
int $port: 连接端口，默认 6379
string $prefix: 要使用的全局键前缀，默认 'PHPProm:'
null|string $dbIndex: 要使用的Redis DB索引，null表示忽略

它非常快，并提供了持久性，因此这是推荐的存储实现。

Memcached

Memcached存储实现需要安装PHP memcached 扩展。其构造函数接受以下参数

string $host: 连接主机
int $port: 连接端口，默认 11211
string $prefix: 要使用的全局键前缀，默认 'PHPProm:'

这种存储实现比Redis还要快，但没有任何持久性，因此如果测量的计数器随时间变化而应保留，则不建议使用。

DBAL

DBAL存储实现需要安装“doctrine/dbal”包以及使用驱动程序的先决条件。目前，已经测试了MySQL、PostgreSQL和SQLite驱动程序。但为了与许多DBAL支持的数据库兼容，已将SQL语句保持简单。如果发现某些功能无法正常工作，请告诉我。

其构造函数接受以下参数

\Doctrine\DBAL\Connection $connection: DBAL连接
string $table: 要使用的表

MySQL表的方案是

 CREATE TABLE `phpprom` (
     `key` varchar(255) NOT NULL,
     `value` double NOT NULL,
     PRIMARY KEY (`key`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

SQLite表的方案是

CREATE TABLE `phpprom` (
	`key`	TEXT NOT NULL UNIQUE,
	`value`	REAL NOT NULL,
	PRIMARY KEY(`key`)
);

PostgreSQL表的方案是

CREATE TABLE public.phpprom (
    key VARCHAR(255) PRIMARY KEY NOT NULL,
    value DOUBLE PRECISION NOT NULL
);
CREATE UNIQUE INDEX phpprom_key_uindex ON public.phpprom (key);