文档/容器/服务/Log

日志服务

Log 服务是 HLEB2 框架中的日志机制，可以将错误和消息存储在专用的日志存储中。框架中的日志存储原则基于 PSR-3。

默认情况下，框架使用内置的日志记录机制，将日志保存到文件中。所有 PHP 错误和应用程序本身的操作都会被记录，还有开发人员在代码中指定的信息和调试日志。

框架的标准文件日志保存在项目中的 /storage/logs/ 文件夹中。

在控制器（以及从 Hleb\Base\Container 继承的所有类）中使用 Log 的方式，通过添加信息性消息进行说明：

// variant 1
use Hleb\Reference\LogInterface;
$this->container->get(LogInterface::class)->info('Sample message');

// variant 2
$this->container->log()->info('Sample message');

应用程序代码中的日志记录示例：

// variant 1
use Hleb\Static\Container;
use Hleb\Reference\LogInterface;
$data = Container::get(LogInterface::class)->info('Sample message');

// variant 2
use Hleb\Static\Log;
Log::info('Sample message');

// variant 3
logger()->info('Sample message');

还可以通过依赖注入根据 Hleb\Reference\Interface\Log 接口获取 Log 对象。

为了简化，以下示例将仅使用 logger() 函数。

执行前面的示例之一会在 /storage/logs/ 目录中创建日志文件（如果之前不存在），并添加以下类似的行：

[13:01:12.211556 10.01.2024 UTC+03] Web:INFO Sample message {/path/to/project/app/Controllers/TestController.php on line 31} {App\Controllers\TestController->get()} GET http://example-domain.ru/test-log 127.0.0.1 #{"request-id":"71cc0539-af41-556d-9c48-2a6cd2d8090f","debug":true}

日志文本显示，输出了一条消息 'Sample message'，具有指定的级别 'INFO'，以及关于日志调用的附加信息、准确时间和基本请求数据。

建议不要将日志内含有机密信息和数据发送到第三方服务进行日志存储，因为这些信息和数据的泄露可能导致项目的安全漏洞，并且这些服务可能容易受到攻击。

#日志级别

选择日志级别时，应根据输出数据的内容和重要性进行指导。从普通消息到严重错误按递增顺序列表如下：

debug() - 调试消息，通常仅在项目开发期间使用。默认情况下，框架设置的最大级别为低于 (info)，这些消息将不会保存到日志中。

info() - 信息性消息，必要时可以了解代码的特定部分是如何工作的以及是否满足所有条件。在此处可以输出具体的SQL查询，以便稍后验证其正确执行。

notice() - 系统中事件的通知。例如，可以提醒某些重要值的临界值接近，但尚未达到。

warning() - 记录异常情况，不作为重大错误，而是作为警告。例如，使用已弃用的 API，错误使用 API，以及其他不希望出现的情况。

error() - 在某些条件下发生的运行时错误。这些错误不需要立即行动，但应记录和监控。

critical() - 程序中的严重错误，例如某个组件不可用。

alert() - 一般系统不可用，例如数据库故障、整个网站停机等。应立即采取行动进行修复。

emergency() - 系统完全不可用。

#日志上下文

根据 PSR-3，您可以将命名数据数组作为第二参数传递，用于消息文本中的替换，例如：

logger()->error('Failed to create user {name}', ['name' => 'Ivar']);

在框架的内置日志中，您还可以将其他数据添加到数组中，它们将按键输出到包含 'request-id' 的日志部分。第三方日志机制可能不支持此功能。

#替代日志记录器

HLEB2 框架仅支持一个活动的日志记录机制实例；如果需要用第三方日志器替换它，则必须在框架初始化期间完成。这种必要性是因为错误记录应从框架本身加载和操作的最开始阶段开始。

#日志设置

在 /config/common.php 文件中：
log.enabled - 启用/禁用日志保存，这在临时禁用日志记录以减少应用程序负载时可能很有用。
max.log.level - 设置最大日志记录级别(从消息到关键错误)。例如，如果将级别设置为 'warning'，则'debug'，'info' 和 'notice' 级别的日志将不会被保存。
max.cli.log.level - 当通过终端或任务调度器使用框架时的最大日志记录级别。
error.reporting - 此参数与错误级别有关，但也与日志记录有关，因为它确定哪些错误会进入日志。
log.sort - 对于标准文件日志记录，将日志按源（网站域）拆分。
log.stream - 如果指定，则将日志输出到指定的输出流，例如在 '/dev/stdout' 中。
log.format - 标准日志记录可用两种格式，'row'（默认）和 'json' ，后者将日志输出转换为 JSON 格式。

在 /config/main.php 文件中：
db.log.enabled - 记录所有对数据库的请求。

#使用示例

展示错误日志记录和常规信息日志之间差异的通用示例：

// Will output to the log.
logger()->info('Info message');

try {
    throw new ErrorException('Warning message');
} catch(\ErrorException $e) {
    // Will output an error to the log and continue execution.
    logger()->warning($e);
}
// Will output an error to the log and interrupt execution.
throw new ErrorException('Error message');

#查看日志

通过文件标准存储日志时，可以使用控制台命令在终端中显示最新添加的日志：

$php console --logs 3 5

指定的命令将显示最近五个日志文件的最后三个日志记录。

在日志记录（默认为文件）中，每个日志条目都有一个 "request-id" 标签，可用于筛选特定请求的所有日志。
对于 UNIX 系统和 macOS，可以使用 'grep' 命令按错误类型搜索：

$grep -m10 :ERROR ./storage/logs/*

此命令的灵活性允许在各种条件下搜索，包括按请求的 "request-id"。

对于 Windows，可以使用 'findstr' 命令作为替代：

D:\project>findstr /S /C:":ERROR" "storage/logs/*"

#日志轮替

框架中包含 App\Commands\RotateLogs 类，这是用于删除过期日志文件的控制台命令实现。

$php console rotate-logs 5

此命令将删除五天前创建的所有日志文件。默认情况下设为三天。该命令适用于手动轮替或添加到任务调度程序（每日执行）。

若要让框架自动监控日志文件的最大大小，请在 /config/common.php 文件中设置 'max.log.size' 选项。该值以兆字节（MB）为单位指定。但在启用该设置的情况下，如果当天日志量意外过大，可能会删除前一天的所有日志。

← 缓存 Path →

页面翻译：chatgpt 4-o

PHP Framework HLEB2

HLEB2