PHP 日志库怎么选:五款主流方案横向对比

PHP 日志库选型中文指南:Monolog、Log4php、KLogger、Analog、error_log/syslog 内置方案的功能、PSR-3 兼容性、维护状态与适用场景对比,附选型决策建议与观测云平台接入方案。

最佳实践
PHP 日志库怎么选:五款主流方案横向对比技术指南封面

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 错误配置

选型决策建议

  1. 新项目:框架已有合用的日志集成时可沿用。需要多个去向、公共字段或格式控制时,可以选 Monolog。
  2. 极简脚本:已有 PHP 错误通道可使用 error_log()。选 KLogger 前核对 psr/log 版本。
  3. 存量 Log4php:先对照现有的级别阈值、布局、目的地和异常记录,再按模块迁移。
  4. 业务代码:使用 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 按样本配置字段映射后,再用各应用的错误记录验证同一检测条件。

系列阅读


[1]: 观测云文档《DataKit 日志采集综述》https://docs.guance.com/integrations/datakit-logging/
[2]: 观测云文档《日志查看器》https://docs.guance.com/logs/explorer/
[3]: 观测云文档《日志-索引》https://docs.guance.com/logs/multi-index/

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台