README

Numero-log是一个用PHP编写的简单的客户端/服务器应用程序，它收集有关命名资源（例如包）的任意数值数据，存储它，并在请求数据时执行计算。

它由一个小型客户端和同样小巧的服务器组成；客户端是您提交收集到的数值数据的主要API - 服务器是您请求数字各种版本的API。

输出非常适合（但不限于）在以JSON作为数据源的图形中显示（使用包含时间和值的二维数组）。

演示

该GIF演示了如何使用自定义令牌创建包的计数器（发生在第一次保存操作中），并记录计数器的额外值。最后，它展示了如何使用统计信息检索这些值。值的收集发生在本地 - 值的存储和计算发生在默认的远程服务器上（开放且免费使用，但可以更改）。注意，使用| json_pp将紧凑格式的JSON“管道”到美化打印。

配套包

• Numerolog Lavacharts使Numerolog计数器的图表输出成为可能；在公共Numerolog服务器上公开可用。请参阅项目页面以了解使用方法！
• Numerolog PHPUnit使单元测试能够基于统计数据进行断言，同时收集新数据。结果是“学习”系统，它不断调整所选指标（内存使用、文件大小、调用的函数、堆栈深度等）的预期限制。

目的

Numero-log让您从远程主机存储和检索仅数值信息，并让您不必担心为数字创建各种存储（这是自动发生的）。在检索数字时，Numero-log还允许您读取有关数据集的基本信息，例如最小值、最大值、平均值和总和。

我们可以用一个基本示例来说明这一点：跟踪温度。

我们不关心如何检索每个温度值，假设您有一个每五分钟运行一次的自动任务来收集温度。您希望将此值存储在远程（这是关键方面：如果您不需要远程存储，则无需使用此包 - 只需使用普通数据库即可）。然后您请求Numero-log每五分钟记录每个数字。收集一段时间后，您就可以查询

• 任何给定时间的温度
• 任何给定时间范围的温度范围
• 任何给定时间范围内的最高温度
• 中值温度
• 等等

数据集以极高的速度以JSON格式返回。快速的响应和JSON格式意味着您可以从JavaScript应用程序中使用它来渲染图形、时间线、峰值警告、趋势预测等。

Numero-log不是实际监控软件的替代品。它旨在作为大型设置的一个轻量级替代品，当您只需要跟踪少量数值统计信息时。.

需求

要使用服务器部分，需要配置一个HTTP服务器，如Apache或Nginx。在紧急情况下，甚至可以使用PHP内建的HTTP服务器。

当您使用与官方免费社区使用的数据服务器一起使用的 Numero-log 时，不需要HTTP服务器（注意：此访问可能在将来发生变化，但 Numero-log 将不会失去与自定义服务器工作的能力）。

要使用命令行和客户端API，您只需要PHP和网络连接。

配置

Numero-log 的配置要求最低 - 实际上，只有一个设置。由于只有一个设置，因此选择将其放在您所在文件夹的 composer.json 文件中。这样做是因为预期的使用方式都以 composer 为核心：即使您只是 require 这个包，composer 也会为您生成 composer.json 文件。

在 composer 文件中，您可以放置此单个设置

{
    "name": "myvendor/mypackage",
    "extra": {
        "namelesscoder/numerolog": {
            "host": "http://mydomain.com/"
        }
    }
}

更改此 host 设置将使 Numero-log 与该主机作为端点（存储）进行通信。然后您可以在该主机上的HTTP服务器上从该包的 web 目录中提供 index.php 文件（复制它，创建符号链接或直接从 vendor 提供服务）。

注意：当与远程存储通信时，Numero-log 还会使用 composer.json 中的 name 设置作为包标识。 您跟踪的每个值都与包相关联。

使用方法

有两种方法可以使用 Numero-log 客户端（显然，服务器部分只有一种操作模式：提供 index.php 并完成）

在命令行模式下，您可以通过调用 ./vendor/bin/numerolog 来报告和获取数据。只需调用不带参数的命令即可获得简短的帮助文本。以下是一些应该立即使您理解的示例命令

# increment "mycounter" by 10
./vendor/bin/numerolog --action save --package myvendor/mypackage \
    --token 1234567890abcdefg1234567890abcdefg
    --counter mycounter --value +10

# record a new temperature measurement
./vendor/bin/numerolog --action save --package myvendor/mypackage \
    --token 1234567890abcdefg1234567890abcdefg
    --counter temperature --value 31.5

# get the most recent recorded temperature
./vendor/bin/numerolog --action get --package myvendor/mypackage \
    --token 1234567890abcdefg1234567890abcdefg
    --counter temperature

# get the twenty most recent recorded temperatures
./vendor/bin/numerolog --action save --package myvendor/mypackage \
    --token 1234567890abcdefg1234567890abcdefg
    --counter temperature --count 20

# get January's recorded temperatures
./vendor/bin/numerolog --action get --package myvendor/mypackage \
    --token 1234567890abcdefg1234567890abcdefg
    --counter temperature --from 2015-01-01 --to 2015-01-31

# get temperatures recorded from January up to today
./vendor/bin/numerolog --action get --package myvendor/mypackage \
    --token 1234567890abcdefg1234567890abcdefg
    --counter temperature --from 2015-01-01

# poll a the maximum recorded temporature over last 30 recoded values
./vendor/bin/numerolog --action poll --package myvendor/mypackage \
    --token 1234567890abcdefg1234567890abcdefg
    --counter temperature --poll max --count 30

get 和 poll 命令在本质上非常相似，支持相同的限制和范围参数，但它们在 poll 仅返回集合中的特定值方面有所不同，例如本示例中的统计计数器。可用于 --poll 的名称是根数组的索引和 statistics 数组的索引。例如，max、average、sum、values 或 statistics 的全部。

请注意，只要您的项目文件夹的 composer.json 文件有 name，就可以省略 --package myvendor/mypackage 参数。然后 Numero-log 将自动使用此值，并且您可以在命令中省略它。请注意，--token 参数也可以设置为环境变量，该变量将由 numerolog 命令使用。使用来自 composer.json 的包和来自环境的令牌，命令可能看起来如下

# passing the "token" as ENV variable; read package from composer.json
NUMEROLOG_TOKEN="1234567890abcdefg1234567890abcdefg" ./vendor/bin/numerolog \
    --action get --counter mycounter --count 10

第二种操作模式是直接通过 PHP

$client = new \NamelessCoder\Numerolog\Client();
$client->get($package, $counter, $count = 1);
$client->getRange($package, $counter, $from, $to = NULL);
$client->save($package, $counter, 3.14);

用于监控和类似 Cacti 的系统

Numero-log 包含一个易于使用的方法来轮询单个 get 响应参数 - 这意味着您无需解析 JSON 即可知道某个值，只需请求该值即可。这意味着 poll 命令非常适合收集单个值并将该值记录下来或执行某些操作。例如，您可能希望当平均温度达到某个特定点时执行某些操作，一个小型的可执行脚本可能非常适合

#!/usr/bin/env bash

# Variable $TEMPERATURE30 will contain a single numerical value which we can check:
TEMPERATURE30=`./vendor/bin/numerolog --action poll --package myvendor/mypackage \
                 --token 1234567890abcdefg1234567890abcdefg
                 --counter temperature --poll average --count 30`

# The value is the average measured across the last 30 recorded values.

if [[ $TEMPERATURE30 -gt 40 ]]; then
    echo "It's getting hot in here!"
    echo "$TEMPERATURE30 degrees on average, hot!"
    exit 1
fi

if [[ $TEMPERATURE30 -lt -10 ]]; then
    echo "It's cold out there today!"
    echo "$TEMPERATURE30 degrees on average, brrr!"
    exit 2
fi

echo "Just right. A perfect $TEMPERATURE30"
exit 0

这意味着您可以执行脚本，任何过高或过低的值都会导致唯一的错误代码。如果温度合适，脚本将以成功代码退出。请注意，对于关键值的实际监控，您可能发现 --poll min 或 --poll max 参数更有信息量。

现在，关于像Cacti这样的监控系统：这类系统通常允许通过脚本收集一个值。将poll命令作为脚本从Numero-log运行，并选择要图形化的值（例如，最后30个值的平均值），这将使监控系统抓取输出的值并将其用于自己的存储中。

这意味着您可以使用Numero-log在任何给定的间隔和任何您想要的地点记录值，例如分布式构建系统或监控站，并使您的“主要”监控系统从单个位置获取这些值，并且只接收平均值；平滑出轮询值。

例如：Numero-log将允许您以非常低的间隔记录值，并且从您想要的任何数量的主机记录，但Cacti通常需要一或五分钟的平均轮询频率，在默认设置下，必须轮询每个主机。因此，在Numero-log中记录频繁的测量值并读取平均值意味着您正在“预处理”统计数据，使其成为一个单一的、图表友好的测量单位，具有固定的轮询间隔（以及您想要的长期存储）。

安全

Numero-log是通过HTTP部分构建的，读取数据时不需要身份验证。如果您只想安全地访问数据，请确保您设置了自己的HTTP服务器并相应地保护它。命令行实用程序允许您创建任意数量的命名跟踪，并在为您的软件包创建数据库时发出单个令牌。令牌仅在第一次响应中返回，必须保存并用于向远程存储报告新数据。

令牌

Numero-log有两种使用令牌的运行方式。第一种是简单地提供令牌作为命令行参数或各种函数的参数 - 第二种是依赖于一个特殊命名的令牌文件：.numerolog-token-{sha1:packagename}。sha1是针对那些与多个页面集成的项目添加的；同时，无论软件包名称如何，都对值进行净化，以创建适当的文件名。

第一种模式，手动提供令牌，要求您在每个请求中使用token参数。第二种模式允许令牌由远程主机自动生成并交付给客户端（然后将其存储在提到的文件中）。如果您的软件包需要自动生成的令牌，只需在第一个计数器执行第一次save操作时省略token。生成的令牌可以备份、加密、与其他开发者共享，用于持续集成等。

令牌以明文形式传输。它不被视为敏感信息，除了您不应该公开分享之外 - 当您需要在例如持续集成中使用它时，使用CI平台上的方法进行加密和解密。但是您如何处理，客户端仍然必须知道令牌的明文格式 - 这意味着该密钥的任何额外加密层都变得冗余。话虽如此：如果您想要额外的安全性，例如，您可以设置自己的Numero-log远程服务器并使用您喜欢的任何类型的加密，例如IP限制（并使每个令牌成为一个简单的虚拟值）。