README

slick/遥测是一个小型库，使用PSR-3兼容的记录器将HTTP/应用程序遥测指标发送到指定的日志服务/系统。它抽象了指标、依赖项、异常、PSR-14 slick实现事件和HTTP 请求的概念。它还实现了PSR-3LoggerInterface，允许将其用作常规记录器。

此包符合PSR-12代码标准和PSR-4自动加载标准。它还遵循语义版本2.0.0规范。

安装

通过Composer

$ composer require slick/telemetry

如果您需要使用slick/遥测与PHP 7.4.x版本一起使用，请执行以下操作

$ composer require slick/telemetry:^1.0

使用方法

要开始使用遥测记录器，您需要一个PSR-3实现，该实现将信息传递到您首选的日志系统。
我们推荐使用由Jordi Boggiano开发的monolog\monolog包及其处理器之一。有关更多信息，请访问Monolog项目网站。

要将monolog\monolog添加到您的项目中，请运行以下命令

$ composer require monolog\monolog

创建遥测客户端

使用一个PSR-3记录器，我们现在准备好创建我们的客户端

<?php

namespace App;

use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Slick\Telemetry\TelemetryClient;

$logger = new Logger('my-app');
$logger->pushHandler(
    new StreamHandler('path/to/your.log', Logger::INFO)
);

$telemetryClient = new TelemetryClient($logger);

注册指标

有2种类型的指标遥测：单次测量和预聚合指标。单次测量只是一个名称和值。预聚合指标指定指标在聚合间隔内的最小值和最大值及其标准差。

<?php

$telemetryClient->trackMetric("Open processes", 345); // measurement
$telemetryClient->tracMetric("Memory", 89.43, 8, 60.3, 94.323, 5) // Pre-aggregated metric

// adding more context to the measurement
$telemetryClient->trackMetric("Open processes", 345, context: ["region" => "north"]);

注册依赖项

依赖项表示应用程序与远程组件（如SQL或HTTP端点）的交互。

<?php

// A SQL example of a dependency entry
$telemetryClient->trackDependency(
    "Query user tasks list",
    "SQL"
    "select * from tasks where user_id = :uid",
    1643808614,
    2.33793258,
    true,
    [
        "database" => "Local MySQL DB",
        "rows" => 23,
        "uid" => 212
    ]
);

注册异常

异常表示在监视应用程序执行过程中发生的已处理或未处理的异常。

<?php
// Handled exception
try {
    // faulty code
} catch (\Exception $e) {
    $telemetryClient->trackException($e);
}

// Unhandled exception
function exception_handler($exception) {
  $telemetryClient->trackException($e);
}

set_exception_handler('exception_handler');
throw new Exception('Uncaught Exception');

注册事件

事件遥测表示在您的应用程序中发生的事件。通常，它是一个用户交互，如按钮点击或订单结账。它也可以是应用程序生命周期事件，如初始化或配置更新。

从语义上讲，事件可能与请求相关或不相关。但是，如果使用得当，事件遥测比请求更重要。事件代表业务遥测。

为了使用此遥测项目，您需要使用slick/event创建事件，它是此库的必需依赖项。slick/event是一个简单的PSR-14事件处理实现库。我们还建议事件对象实现JsonSerializable接口，以便将数据作为上下文传递到日志服务。

<?php

namespace App;
 
use Slick\Event\Domain\AbstractEvent;
use Slick\Event\Event as SlickEvent;

/**
 * Event class example
 */
class TaskWasFinished extends AbstractEvent implements SlickEvent, \JsonSerializable
{
    public function __construct(private int $taskId)
    {
        parent::__construct();
    }
    
    public function jsonSerializa()
    {
        return ['taskId' => $this->taskId];
    }
}

// track the event
$telemetryClient->trackEvent(new TaskWasFinished(34));

注册HTTP请求

可以使用HTTP请求注册请求的信息：路径、持续时间、POST数据或头信息可以在此注册。

单次调用

<?php

$telemetryClient->trackRequest(
    'create user',
    '/users',
    1643887671,
    201,
    276.4379,
    $_REQUEST
);

请求工厂方法

使用这些方法，我们可以让遥测客户端为我们计算时间和持续时间。这是通过注册 beginRequest() 和 endRequest() 方法调用之间的差异来完成的。

让我们看一个例子

<?php
// front-controller script
$trackableRequest = $telemetryClient->beginRequest('create user', '/users', $_REQUEST);

// front-controller execution code

$telemetryClient->endRequest($trackableRequest, 201);

此代码与调用 TelemetryClient::trackRequest() 方法一次所产生的作用相同

其他功能

消息插值

在所有对 TelemetryClient::track() 或 TelemetryClient::log() 方法的调用中，您需要在消息参数中设置占位符，以便它们可以被上下文字符数组中的值替换。您需要遵循以下规则

占位符名称必须与上下文字符数组中的键相对应；
占位符名称必须用单个开大括号 { 和单个闭大括号 } 分隔；
分隔符和占位符名称之间不得有任何空格。

<?php

$telemetryClient->notice(
    "User {name}, was suspended because {reason}.",
    ["name" => "John Doe", "he had too many login attempts"]
);

// Resulting message will be:
// User John Doe, was suspended because he had too many login attempts.

日志级别覆盖

所有方法都有一个默认的 logLevel。对于所有默认值是 LogLevel::INFO，除了 TrackableException，其中默认值为 LogLevel::ERROR。

此外，如果其 isSuccessfull 属性为 false，则 Dependency 和 Request 可以有 LogLevel::WARNING。

如果您通过将 level 键传递给上下文参数，则可以更改此日志级别。

<?php

// Override LogLevel::INFO with LogLevel::WARNING in a metric register
$telemeteryClient->trackMetric('free space', 20, context: ['level' => LogLevel::WARNING]);

测试

我们使用 PHPSpec 进行单元测试。

# unit tests with phpspec
$ composer test

贡献

有关详细信息，请参阅 CONTRIBUTING。

安全

如果您发现任何与安全相关的问题，请通过电子邮件 [email protected] 而不是使用问题跟踪器。

鸣谢

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件。

slick / 遥测

维护者

详细信息