PHP 日志库怎么选:五款主流方案横向对比
PHP 日志库选型中文指南:Monolog、Log4php、KLogger、Analog、error_log/syslog 内置方案的功能、PSR-3 兼容性、维护状态与适用场景对比,附选型决策建议与观测云平台接入方案。
PHP 日志生态的格局非常清晰:Monolog 常见于框架应用,其余方案各守一隅。本文横向对比五种方案,帮你快速确认“我的项目该用哪个”。
核心要点速览
- Monolog:实现 PSR-3,Laravel 的日志频道以它为基础,Symfony 可通过 MonologBundle 接入。
- Log4php、KLogger 和 Analog:Log4php 已归档。后两者可提供较小的接口或输出层,但应先核对
psr/log版本。 - 内置 error_log/syslog:可由应用代码调用,也可与 PHP 运行时错误输出接入同一系统。两者的目的地配置和级别参数不同。
- 平台侧与选型解耦:统一输出格式后,再验证换库是否影响已有采集和查询。
五款方案对比表
| 方案 | PSR-3 | 结构化 | 多目的地 | 维护状态 | 适合谁 |
|---|---|---|---|---|---|
| Monolog | 3.12.1 依赖 psr/log 2.x 或 3.x |
context + Formatter | 多种 Handler | 仍有新发布 | 需要按级别、去向和格式配置日志的应用 |
| Log4php | 原包自有 Logger API | 支持 Pattern、XML 等布局 | Appender | 官方仓库归档,Composer 包标记 abandoned | 存量维护和迁移 |
| KLogger | 1.2.2 依赖 psr/log 1.x |
可配文本格式和 context | 主要写文件 | 1.2.2 发布于 2022 年 | 已锁定兼容接口版本的简单文件日志 |
| Analog | 1.0.21-stable 的 Analog\Logger 依赖 psr/log 3.x |
输出由 handler 决定 | 文件、stderr 等 handler | 该稳定版发布于 2023 年 | 需要简单或自定义输出的应用 |
| error_log/syslog | PHP 原生函数 | 接收消息字符串,无统一 context 格式 | 由 PHP、SAPI 或系统配置决定 | PHP 内置 | 小脚本、运行时诊断或已有系统日志路由 |
逐款点评
1. Monolog:事实标准
Handler 决定去向,Processor 可以补充公共字段,Formatter 决定输出格式。RotatingFileHandler 支持按日期切换文件和保留数量。JsonFormatter 可以把记录编码成 JSON,但字段结构仍要和下游约定。Laravel 使用 Monolog 支撑日志频道,Symfony 可以安装 MonologBundle。PHP 引擎和进程的日志仍要检查实际的收集路径。Monolog 用法 · Laravel 日志 · Symfony 日志
2. Log4php:Apache 血统的老将
Log4php 是 log4j 的 PHP 移植,保留层级 Logger、Appender 和 XML 等配置方式。原包的 Logger API 未实现 PSR-3。Apache 的 GitHub 镜像已归档,Composer 包已标记 abandoned。维护存量项目时,先盘点自定义 Appender 和 Layout,再决定迁移顺序。Apache 归档仓库 · Composer 包状态
3. KLogger:极简 PSR-3
KLogger 1.2.2 写文件,默认文件名包含日期,支持级别阈值和格式配置。这个版本依赖 psr/log 1.x,与要求 2.x 或 3.x 的依赖放在同一个 Composer 项目时可能无法解析。默认按日期命名不等于有保留期清理,仍需管理磁盘和旧文件。KLogger 包与选项
4. Analog:轻量多输出
Analog 提供静态入口和可接收自定义闭包的 handler。要注入 PSR-3 接口,用 Analog\Logger 包装器。1.0.21-stable 依赖 psr/log 3.x,输出是否结构化取决于所用 handler。Analog 用法 · Composer 版本约束
5. 内置 error_log/syslog:由运行环境决定去向
应用代码可以直接调用这两个函数。默认的 error_log($message) 走 PHP 配置的错误日志路径,具体落点随 error_log 配置和 SAPI 变化。类型 3 直接追加到指定文件,需要自己写换行。类型 0 返回 true 不能证明写入成功。syslog(LOG_ERR, $message) 可以指定优先级,最终路由由系统日志机制决定。PHP 引擎错误的记录还受 log_errors 和运行环境配置影响。error_log 文档 · syslog 文档 · PHP 错误配置
选型决策建议
- 新项目:框架已有合用的日志集成时可沿用。需要多个去向、公共字段或格式控制时,可以选 Monolog。
- 极简脚本:已有 PHP 错误通道可使用
error_log()。选 KLogger 前核对psr/log版本。 - 存量 Log4php:先对照现有的级别阈值、布局、目的地和异常记录,再按模块迁移。
- 业务代码:使用
Psr\Log\LoggerInterface接收日志实现。换库后仍需核对实际输出和采集规则。
更换日志库后验证字段
从 Log4php 或其他库迁到 Monolog 时,先对照两组正常与异常日志,检查时间、级别、channel 和 context 的变化。以 Monolog 3.12.1 的 JsonFormatter 为例,level 为数字,level_name 为级别名称,datetime 记录时间,异常位于 context.exception。原来匹配 level=ERROR 的查询需要按实际落库字段调整。Monolog JsonFormatter
日志已通过观测云 DataKit 采集时,用这些样本验证 Pipeline 和现有错误查询。即使两边都输出 JSON,字段名或嵌套层级变化也可能需要调整解析。DataKit 日志采集
常见问题(FAQ)
PSR-3 为什么这么重要?
它是 PHP 日志的统一调用接口。业务代码可以依赖 Psr\Log\LoggerInterface,由应用选择实现。PSR-3 约定级别、消息和 context,异常可放在 exception 键中。它没有规定 JSON 字段、写入目标或保留策略,换库仍需核对这些行为。PSR-3 规范
Monolog 性能怎么样?
取决于 Handler、Formatter、日志量和目的地。同步网络 Handler 的延迟可能占用 PHP-FPM worker。写本地文件或标准输出后交给采集器是一个选择,但仍需测量实际写入开销。缓冲 Handler 可以批量写入,缓冲未落地时也可能在异常退出中丢失。
Symfony 项目和 Laravel 的日志配置思路一样吗?
Laravel 用 config/logging.php 配置日志频道。Symfony 自带简易 PSR-3 logger,安装 MonologBundle 后可在 config/packages/monolog.yaml 等文件配置 handler 和 channel。只有实际使用 Monolog 时,两边才共享相关概念。
多个 PHP 应用的日志字段怎么统一?
制定团队 JSON 契约(time/level/channel/message/context 字段命名),各应用用 Monolog Processor/Formatter 落实。观测云 Pipeline 按样本配置字段映射后,再用各应用的错误记录验证同一检测条件。
系列阅读
- 上一篇:Log4php 实战指南
- 下一篇:PHP 应用 OpenTelemetry 可观测性实战
- 相关阅读:Monolog 实战 · 如何选择日志框架
[1]: 观测云文档《DataKit 日志采集综述》https://docs.guance.com/integrations/datakit-logging/
[2]: 观测云文档《日志查看器》https://docs.guance.com/logs/explorer/
[3]: 观测云文档《日志-索引》https://docs.guance.com/logs/multi-index/