README

php-seq

一个用于 Seq (由 datalust 提供的) HTTP 入口服务的 PHP 库。

安装

composer require ricardoboss/php-seq

用法

// 0. gather dependencies (preferably using dependency injection)
$httpClient = getPsr18Client(); // PSR-18 (HTTP Client)
$requestFactory = getPsr17RequestFactory(); // PSR-17 (HTTP Factories)
$streamFactory = getPsr17StreamFactory(); // PSR-17 (HTTP Factories)

// 1. create the Seq client
$clientConfig = new SeqHttpClientConfiguration("https://my-seq-host:5341/api/events/raw", "my-api-key");
$seqClient = new SeqHttpClient($clientConfig, $httpClient, $requestFactory, $streamFactory);

// 2. create the logger
$loggerConfig = new SeqLoggerConfiguration();
$logger = new SeqLogger($loggerConfig, $seqClient);

// 3. start logging!
$logger->send(SeqEvent::info("Hello from PHP!"));
// or
$logger->info("Hello via PSR-3!"); // or $logger->log(\Psr\Log\LogLevel::INFO, "...");

// using message templates:
$logger->info('This is PHP {PhpVersion}', ['PhpVersion' => PHP_VERSION]);

// (optional) 4. force sending all buffered events
$logger->flush();

注意

当调用日志记录器的 __destruct 方法时（即在运行时最晚关闭时），所有事件都会自动刷新。

您可以使用 example 文件夹中的示例项目来尝试不同的事情。它使用 guzzlehttp/guzzle 作为其 PSR 实现。

配置

配置分为实际客户端（发送请求）和收集事件并将它们转发给客户端的日志记录器。这使得可以使用相同的客户端创建多个具有不同上下文/最小日志级别的日志记录器。此外，它还使我们能够将来实现其他接口的新客户端（参见下文的“未来范围”）。

SeqHttpClientConfiguration

SeqLoggerConfiguration

高级用法

消息模板 & 上下文

Seq 支持消息模板语法。您可以使用上下文参数来使用它。

$username = "EarlyBird91";

// Will log "Created EarlyBird91 user" to Seq with the "username" attribute set to "EarlyBird91"
$logger->info("Created {username} user", ['username' => $username]);

注意

上下文值将被转换为字符串。如果它们不是标量或 Stringable 对象，则使用 json_encode 进行编码。

自定义 Seq 事件

Seq 使用 CLEF 格式进行 HTTP 入口，该格式由本库使用。为了您的方便，您可以直接使用 SeqEvent 类访问 CLEF 格式的所有属性。

只需创建一个新实例，并通过 SeqLogger 发送它，或使用 json_encode 对其进行编码。

$event = new SeqEvent(
    new DateTimeImmutable(),
    "message",
    "messageTemplate",
    "level",
    new Exception("exception"),
    123,
    ['attribute' => 'rendered'],
    ['tag' => 'value'],
);

$logger->send($event);
// or
echo json_encode($event); // {"@t":"2023-05-16T12:00:01.123456+00:00","@mt":"messageTemplate",...}

请注意，如果您以这种方式创建事件，您仍然需要自行验证事件。您可以从 Seq 的此处检查要求：[Reified properties](https://docs.datalust.co/docs/posting-raw-events#reified-properties)

使用 @ 对用户属性进行转义，在将事件编码为 JSON 时会自动进行。

最小日志级别

您可以使用 SeqLoggerConfiguration 类的 $minimumLogLevel 构造函数参数指定日志记录器将缓冲并发送到 Seq 的最小日志级别。

$config = new SeqLoggerConfiguration(minimumLogLevel: SeqLogLevel::Warning);

这将仅允许发送 Warning 或更严重的事件到 Seq（如 Error 和 Fatal）。

您也可以在运行时调整日志记录器的最小日志级别。

$previousLogLevel = $logger->getMinimumLogLevel();

$logger->setMinimumLogLevel(SeqLogLevel::Information);

动态级别控制

Seq 支持一种称为“动态级别控制”的方案，该方案允许客户端根据其 API 密钥的配置调整其最小日志级别。

php-seq 也支持此功能，并将根据 Seq 的响应调整每个日志记录器的最小日志级别。

您可以在 Seq 的网站上了解动态级别控制：[Seq 的动态级别控制](https://docs.datalust.co/docs/using-serilog#dynamic-level-control) 或在 Nicholas Blumhardt 的这篇简短博客文章中了解：[使用 Seq 的远程级别控制](https://nblumhardt.com/2016/02/remote-level-control-in-serilog-using-seq/)

错误处理

由本库抛出的所有异常都实现了 \RicardBoss\PhpSeq\Contract\SeqException 接口。这使得捕获本库包装的任何异常变得容易。

未来范围

本库的目标是为 PHP 中的 Seq 提供简单的日志记录，并保持与当前 PHP 和 Seq 版本的兼容性。

为这个库添加一个可能的功能是使用 sockets 扩展，用 GELF 代替 HTTP，但目前没有这个计划。

贡献

欢迎所有形式的贡献！如果您缺少某个特定功能或者某些功能不符合预期，请在 GitHub 上创建一个问题：[创建问题](https://github.com/ricardoboss/php-seq/issues/new)。

如果您能，我们鼓励您创建一个 pull request。请确保您为您添加或更改的功能添加测试，并确保它们通过。

许可证

本项目的许可证为 MIT 许可证。更多信息请见[许可证](https://github.com/ricardoboss/php-seq/blob/HEAD/./LICENSE.md)。