README

这是一个用于记录指标的 Composer 模块。

安装

composer require stickee/instrumentation

配置

基本用法

要使用基本功能，您必须创建一个仪器导出器并将事件记录到其中。

use Stickee\Instrumentation\Exporters\Exporter;
use Stickee\Instrumentation\Exporters\Events\LogFile;
use Stickee\Instrumentation\Exporters\Spans\NullSpans;

// Create the exporter
$exporter = new Exporter(new LogFile('/path/to/file.log'), new NullSpans());

// Log an event
$exporter->event('some_event');

静态访问器（非 Laravel 项目，对于 Laravel 使用 Facade）

您可以通过将其分配给 Instrument 类来静态地访问您的导出器。

use Stickee\Instrumentation\Exporters\Exporter;
use Stickee\Instrumentation\Exporters\Events\LogFile;
use Stickee\Instrumentation\Exporters\Spans\NullSpans;
use Stickee\Instrumentation\Instrument;

// Create the exporter
$exporter = new Exporter(new LogFile('/path/to/file.log'), new NullSpans());

// Assign to the Instrument class
Instrument::setExporter($exporter);

// Log an event
Instrument::event('some_event');

事件类型

在 Stickee\Instrumentation\Exporters\Interfaces\EventsExporterInterface 接口中定义了 3 个事件类型方法。

标签应该是一个关联数组 tag_name => tag_value，例如。

$tags = ['datacentre' => 'uk', 'http_status' => \Symfony\Component\HttpFoundation\Response::HTTP_OK];

错误

发生错误时，将抛出异常。如果您想捕获所有仪器异常并将它们传递给您的自定义错误处理器，可以在数据库上调用 setErrorHandler 并传递一个接受 \Exception 作为参数的回调函数。

use Exception;

$exporter->setErrorHandler(function (Exception $e) {
    report($e);
});

事件导出器

事件导出器是实现了 Stickee\Instrumentation\Exporters\Interfaces\EventsExporterInterface 接口的类。本模块包含以下类

注意：仅推荐 OpenTelemetry 和 InfluxDb 用于生产环境。其他的是用于开发/调试。

跨度导出器

跨度导出器是实现了 Stickee\Instrumentation\Exporters\Interfaces\SpansExporterInterface 接口的类。本模块包含以下类

Laravel

安装

首先用 Composer 正常安装

composer require stickee/instrumentation

此模块包含 Laravel 服务提供者和 Facade，它们将被自动注册。

如果您使用 InfluxDb，则可以简单地安装包（见下文），在 .env 文件中设置 INSTRUMENTATION_EVENTS_EXPORTER（如果需要，还可以设置 INSTRUMENTATION_INFLUXDB_*），然后在您的代码中使用 Facade - 无需进一步配置

use Instrument;

Instrument::event('Hello World');

手动注册

您可以通过将此添加到 config/app.php 中的 providers 数组来手动注册模块

Stickee\Instrumentation\Laravel\ServiceProvider::class,

如果您想使用 Instrument Facade，请将此添加到 config/app.php 中的 facades 数组

'Instrument' => Stickee\Instrumentation\Laravel\Facade::class,

配置

默认情况下，配置使用 Null 导出器，它们丢弃发送给它们的任何数据。要更改此设置，请在 .env 中设置 INSTRUMENTATION_EVENTS_EXPORTER 和 / 或 INSTRUMENTATION_SPANS_EXPORTER，并添加任何其他所需的变量。

如果您愿意，可以使用发布命令将包配置复制到本地配置，但在正常使用中这是 不必要的

php artisan vendor:publish --provider="Stickee\Instrumentation\Laravel\ServiceProvider"

使用 Open Telemetry

安装 OpenTelemetry 包：composer require open-telemetry/exporter-otlp:^1.0 open-telemetry/opentelemetry-logger-monolog:^1.0 google/protobuf
发布 OpenTelemetry 配置：php artisan vendor:publish --provider="PlunkettScott\LaravelOpenTelemetry\OtelServiceProvider" --tag=otel-config
建议 - 将 OTEL_ENABLED 更改为 INSTRUMENTATION_ENABLED
设置所需的 .env 变量 INSTRUMENTATION_EVENTS_EXPORTER 和 INSTRUMENTATION_OPENTELEMETRY_*

使用 InfluxDb

安装 InfluxDB PHP 客户端：composer require influxdata/influxdb-client-php
设置所需的 .env 变量 INSTRUMENTATION_EVENTS_EXPORTER 和 INSTRUMENTATION_INFLUXDB_*

使用自定义数据库

如果您想为 INSTRUMENTATION_EVENTS_EXPORTER 使用自定义数据库类，那么您只需实现 Stickee\Instrumentation\Exporters\Events\DatabaseInterface 并确保它可以由服务容器构建。

开发

修改项目最简单的方法是将导入模块的项目配置为从您的文件系统而不是Composer仓库加载模块，例如这样

composer remove stickee/instrumentation

编辑composer.json并添加以下内容

"repositories": [
        {
            "type": "path",
            "url": "../instrumentation"
        }
    ]

其中“../instrumentation”是您检出此项目的路径。

composer require stickee/instrumentation

注意：不要这样提交您的composer.json！

测试

测试使用Pest测试框架编写，并使用Orchestra测试平台来模拟Laravel环境。为了确保广泛的兼容性，这些测试通过GitHub Actions在支持的PHP、操作系统和Laravel版本矩阵中运行。

您可以通过调用Pest在您的系统上运行测试。

./vendor/bin/pest

数据库和可视化

OpenTelemetry

前往./vendor/stickee/instrumentation/docker/opentelemetry并运行docker compose up。这将启动Grafana、Loki、Tempo InfluxDB和OpenTelemetry Collector，并在您的本地机器上暴露它们。

Grafana：https://:3000
OpenTelemetry Collector：https://:4318（应使用此地址的INSTRUMENTATION_OPENTELEMETRY_DSN）
InfluxDB：https://:8086（应使用此地址的INSTRUMENTATION_INFLUXDB_URL）

InfluxDB

前往./vendor/stickee/instrumentation/docker/influxdb并运行docker compose up。这将启动Chronograf和InfluxDB，并在您的本地机器上暴露它们。

Chronograf：https://:8888
InfluxDB：https://:8086（应使用此地址的INSTRUMENTATION_INFLUXDB_URL）

贡献

欢迎对项目的所有领域做出贡献，但请提供测试。代码风格将通过Stickee Canary在您的pull request中自动检查。但是，您可以使用上述链接中的说明在本地安装它。

许可证

Instrumentation是开源软件，使用MIT许可证许可。

stickee / instrumentation

维护者

详细信息