Log4php 实战指南：Apache 血统的 PHP 日志框架

Log4php 是 Apache log4j 的 PHP 移植，继承了 Logger/Appender/Layout 的经典三层架构，在 PHP 老项目（尤其有 Java 背景团队的项目）中广泛使用。本文讲解其配置与用法、现状评估，以及存量系统的观测云落地方案。

核心要点速览

• 架构与 log4j 一致：Logger 分层命名、Appender 决定去向、Layout 决定格式——Java 工程师零学习成本。
• XML 声明式配置：appender 与 logger 的路由关系一目了然，改配置不改代码。
• 现状：维护趋缓，Monolog 已是 PHP 主流——新项目选 Monolog；Log4php 存量系统继续维护即可。
• 存量落地：JSON 化或规范格式输出文件，观测云 DataKit 采集解析。

快速上手

composer require apache/log4php

<?php
require __DIR__ . "/vendor/autoload.php";

\Logger::configure(__DIR__ . "/log4php.xml");

$logger = \Logger::getLogger("order-service");
$logger->debug("调试细节");
$logger->info("订单创建", ["order_id" => 1024]);
$logger->warn("库存不足");
$logger->error("扣款失败", $e);   // 异常对象直接传入
$logger->fatal("系统级故障");

级别沿用 log4j 体系：TRACE → DEBUG → INFO → WARN → ERROR → FATAL。

XML 配置：appender + logger

<configuration xmlns="http://logging.apache.org/log4php/">
  <appender name="file" class="LoggerAppenderRollingFile">
    <param name="file" value="logs/app.log" />
    <param name="maxFileSize" value="100MB" />
    <param name="maxBackupIndex" value="10" />
    <layout class="LoggerLayoutPattern">
      <param name="conversionPattern" value="%date{Y-m-d H:i:s,u} %-5level %logger - %msg%newline" />
    </layout>
  </appender>
  <appender name="errorFile" class="LoggerAppenderFile">
    <param name="file" value="logs/error.log" />
    <filter class="LoggerFilterLevelRange">
      <param name="levelMin" value="error" />
    </filter>
  </appender>
  <logger name="order-service">
    <level value="INFO" />
    <appender_ref ref="file" />
    <appender_ref ref="errorFile" />
  </logger>
</configuration>

要点：LoggerAppenderRollingFile 内建轮转（按大小 + 保留份数）；Filter 可实现"error 单独存档"这类精确路由；logger 按点分层级继承（order-service.pay 继承 order-service 配置）。

PatternLayout 常用占位符

现状与迁移建议

• 优势：架构经典、配置表达力强、稳定；
• 短板：社区活跃度低、无 PSR-3 接口、无原生 JSON Layout（需自定义）、生态被 Monolog 全面超越；
• 建议：新项目选 Monolog（Laravel/Symfony 事实标准）；存量 Log4php 系统继续维护，需要结构化时自定义 JSON Layout（LoggerLayoutSerialized 或扩展类）即可平滑接入现代日志平台；迁移期可用 PSR-3 适配层逐步替换。

观测云落地：Log4php 日志采集与分析

1. 应用侧：RollingFile appender 输出到固定目录；有条件时自定义 JSON Layout 输出结构化日志（DataKit 自动解析）；纯文本 PatternLayout 也可由 Pipeline grok 解析。
2. DataKit 采集：conf.d/log/logging.conf 的 logfiles 指向 logs/*.log，source: php-app、service 标识服务。
3. Pipeline 标准化：级别映射标准 status，时间解析为 time；纯文本格式用 grok 提取级别、logger、消息。
4. 检索告警：日志查看器按 status/service 过滤聚类；监控器对 error/fatal 设阈值，通知对象发钉钉/企业微信/飞书。
5. 成本控制：多索引按级别拆保留策略，历史数据转发归档。

常见问题（FAQ）

Log4php 和 Monolog 能共存吗？

能，但建议尽快统一：两套体系的格式与文件分散会让采集与解析规则翻倍。过渡期让两者写到同一目录，DataKit 一并采集，再按模块迁移到 Monolog。

Log4php 的配置能热重载吗？

支持：\Logger::configure($file, $watch) 或配置 LoggerConfigurator 的 watch 机制定期检查变更。生产环境用得上，但注意 PHP-FPM 多进程各自检查的微小延迟。

为什么我的 pattern 里 %throwable 没输出？

异常必须作为日志调用的参数传入（$logger->error("msg", $e)），Layout 才会渲染堆栈。只传字符串消息是没有堆栈可输出的。

多 PHP-FPM 进程写同一文件安全吗？

Log4php 文件写入有锁保护，多进程追加是安全的；但 RollingFile 轮转瞬间多进程并发可能产生边缘问题，大流量站点建议按主机分目录或用采集层（DataKit）统一汇聚。

系列阅读

• 上一篇：Laravel 日志实战
• 下一篇：PHP 日志库五款对比
• 相关阅读：Monolog 实战 ｜ Logrotate 日志轮转实战

---