Download the PHP package sllhsmile/hyperf-log without Composer

Hyperf Log

面向 Hyperf 3 的结构化日志与请求链路追踪包。它统一采集 HTTP API、数据库、Redis 和 Guzzle 调用日志，并在同一协程链路中复用 request ID。

特性

要求

• PHP >= 8.2
• Hyperf ^3.2

安装

Packagist

Packagist 注册完成后：

GitHub 仓库

尚未注册 Packagist 时，在宿主项目的 composer.json 中加入：

然后安装：

发布链路配置：

Hyperf 会通过 ConfigProvider 自动注册本包的 Listener、Aspect 和 HTTP Middleware。

快速配置

本包不会覆盖宿主项目的 config/autoload/logger.php。在 logger.channels 中添加所需 channel；下例复用 default 的 handler 与 formatter，因此所有结构化日志均写入同一个 file.log：

CustomizeJsonFormatter 输出单行 JSON。采集器日志会将 sdklog、dblog 等记录类型写入 message_type，并将其 context 平铺到顶层；普通日志（没有 context）使用 {app_name}_log 作为 message_type，原文保留在 message。datetime、message_type、 request_id、coroutine_id 是保留字段，不会被 context 覆盖。

宿主应用可按自身部署方式设置默认文件 handler：

链路追踪

发布后的 config/autoload/trace_log.php 控制 request ID 与 Guzzle 默认行为：

HTTP 请求和 CLI 命令会自动建立 trace：入站 request_id 缺失时生成 UUID v7，写入请求、 协程 Context 和 HTTP 响应 Header；Guzzle 与异步日志子协程会继承同一个 ID。宿主项目可继续 调用 getRequestId()，它会委托给本包的 RequestContext。

• 有效的上游 x-b3-traceid 会原样透传。
• Header 缺失或为空时，会生成 UUID v7，并写入协程 Context 与后续请求对象。
• Guzzle 自动带上 request ID 与开始时间；公共包仅为 Hyperf 协程 Handler 回写 Swoole 超时配置，优先级为调用方 swoole.*（如有）、调用方顶层 timeout / connect_timeout、trace_log.guzzle 的显式配置、Swoole 默认行为；不会修改普通 cURL Guzzle Handler 使用的顶层超时参数。
• CLI 会通过 BeforeHandle 初始化链路。RPC 或其他后台协程请在入口注入 RequestContext 并调用 initializeTrace()。

注意事项

• API 日志依赖 HTTP server 的 enable_request_lifecycle=true。
• 请求/响应 body、Header、SQL bindings 和 Redis 参数可能含敏感信息；生产环境应在 formatter 或 processor 中脱敏。
• 已有同类 Listener、Middleware 或 Guzzle Aspect 时，请关闭其中一套，避免重复日志和重复 Header 注入。
• 使用 handlers => ['default'] 时，四类日志会写入同一文件；如需分文件，请为每个 channel 配置独立 handler。

本地开发

推荐将包以独立 Git 仓库放在业务项目同级目录：

宿主项目使用 Composer path repository 软链接本地包：

执行一次更新后，vendor/sllhsmile/hyperf-log 会软链接到本地目录；后续修改包代码可立即在宿主项目中调试：

测试与发布

在包仓库目录执行：

发布前确认测试通过后：

License

MIT. See LICENSE.