PHP Monolog 日志实战详解:级别、Handler、Processor 与 Symfony 配置

作者:唐青枫日期:2026/10/9

PHP Monolog 日志实战详解:级别、Handler、Processor 与 Symfony 配置

程序运行出错时,日志往往是还原现场最直接的线索。只用 echo 或 var_dump() 排查,开发时勉强够用,到了线上就很难按级别筛选、按请求追踪,也不适合把告警发到不同地方。

Monolog 是 PHP 生态里常用的日志库,实现了 PSR-3 日志接口。它能把日志写入文件、PHP 错误日志、Syslog 或其他服务,也能给日志补充请求 ID、用户 ID、内存用量等上下文。

这篇文章从一段可以运行的独立 PHP 示例开始,再讲日志级别、Handler、Processor、Formatter 和 Symfony 集成配置。

Monolog 是什么?

Monolog 是负责记录和分发日志的 PHP 库。它实现 PSR-3 的 Psr\Log\LoggerInterface,因此业务代码可以依赖接口,而不必绑定某一个具体日志实现。

Monolog 的核心工作流可以概括成:

1业务代码调用 Logger
2        ↓
3日志记录经过 Processor 补充上下文
4        ↓
5Logger 按 Handler 栈传递记录
6        ↓
7Handler 按级别过滤并决定输出位置
8        ↓
9Formatter 把记录变成文本、JSON 等格式
10

几个核心概念:

  • Logger:日志入口,通常带有一个 Channel 名称。
  • Handler:决定日志写到哪里,以及哪些级别的日志会被接收。
  • Processor:在输出前给日志补充或调整信息。
  • Formatter:把日志记录转换成最终输出格式。
  • Channel:标记日志来源,例如 app、request、payment。

Monolog 不是 Symfony EventDispatcher,也没有叫“事件监听器”的核心机制。Monolog 自己通过 Processor 和 Handler 管理日志记录;Symfony 的事件监听器可以调用 Monolog 写日志,但那是两个组件的配合。

安装 Monolog

独立 PHP 项目安装:

1composer require monolog/monolog
2

Monolog 3.x 要求 PHP 8.1 或更高版本。Symfony 项目一般使用 MonologBundle 将 Monolog 接入服务容器和 YAML 配置:

1composer require symfony/monolog-bundle
2

独立 PHP Demo:把日志写成 JSON 文件

创建 app.php:

1<?php
2
3require __DIR__ . '/vendor/autoload.php';
4
5use Monolog\Formatter\JsonFormatter;
6use Monolog\Handler\StreamHandler;
7use Monolog\Level;
8use Monolog\Logger;
9use Monolog\Processor\PsrLogMessageProcessor;
10
11$logger = new Logger('shop');
12
13$handler = new StreamHandler(
14    __DIR__ . '/var/log/shop.log',
15    Level::Debug,
16);
17$handler->setFormatter(new JsonFormatter());
18
19$logger->pushHandler($handler);
20$logger->pushProcessor(new PsrLogMessageProcessor());
21
22$logger->info('订单 {order_id} 创建成功', [
23    'order_id' => 10086,
24    'user_id' => 42,
25]);
26
27try {
28    throw new RuntimeException('库存服务暂时不可用');
29} catch (Throwable $exception) {
30    $logger->error('订单处理失败', [
31        'order_id' => 10086,
32        'exception' => $exception,
33    ]);
34}
35

运行:

1php app.php
2

日志会写入 var/log/shop.log。如果目录不存在,需要先创建:

1mkdir -p var/log
2

输出为 JSON Lines,一行一条记录,大致如下:

1{"message":"订单 10086 创建成功","context":{"order_id":10086,"user_id":42},"level":200,"level_name":"INFO","channel":"shop","datetime":"2026-10-08T...","extra":{}}
2

PsrLogMessageProcessor 会把消息中的 {order_id} 替换成 context 对应的值。原始 context 仍会保留在结构化字段中,便于日志平台检索。

日志级别:先分清严重程度

PSR-3 定义了八个级别,从低到高依次是:

1debug < info < notice < warning < error < critical < alert < emergency
2

常见用法:

级别常见场景
debug调试细节,例如分支选择、SQL 参数摘要
info正常业务节点,例如订单创建、用户登录
notice值得记录但不算错误的特殊情况
warning可恢复异常,例如第三方请求重试后成功
error单次操作失败,需要排查
critical关键模块不可用或持续失败
alert需要尽快处理的高危故障
emergency系统整体不可用

级别不仅是写日志时的标签,也常用作 Handler 的过滤门槛。Handler 设置为 Level::Warning 后,会接收 warning 及更严重的记录,忽略 debug、info 和 notice。

PSR-3 的 logger 方法也可以直接使用:

1$logger->debug('查询参数已解析', ['page' => 2]);
2$logger->info('订单已创建', ['order_id' => 10086]);
3$logger->warning('支付服务响应较慢', ['duration_ms' => 1800]);
4$logger->error('支付失败', ['order_id' => 10086]);
5

Handler:日志往哪里写?

Handler 是 Monolog 的输出端。一个 Logger 可以有多个 Handler,让同一条日志同时写文件、输出到 stderr,或者发送到告警渠道。

常见 Handler:

  • StreamHandler:写入文件、php://stdout、php://stderr 等 PHP Stream。
  • RotatingFileHandler:按日期切分文件,并保留指定天数。
  • ErrorLogHandler:写入 PHP error_log()。
  • SyslogHandler:写入系统 Syslog。
  • FingersCrossedHandler:先暂存低级别记录,达到指定级别后再统一交给下层 Handler。
  • BufferHandler:先缓存日志,满足条件或关闭时再批量处理。
  • NullHandler:丢弃日志,常用于禁用某个输出分支。

按级别分流

例如普通日志进入滚动文件,错误日志单独写文件:

1use Monolog\Handler\RotatingFileHandler;
2use Monolog\Level;
3
4$logger->pushHandler(new RotatingFileHandler(
5    __DIR__ . '/var/log/app.log',
6    14,
7    Level::Debug,
8));
9
10$logger->pushHandler(new RotatingFileHandler(
11    __DIR__ . '/var/log/error.log',
12    30,
13    Level::Error,
14));
15

默认 bubble 为 true,所以 error 及以上级别的记录也会继续写入普通日志文件。若错误日志只希望进入专用文件,可将错误 Handler 的 bubble 设为 false。

这里的 maxFiles 表示最多保留多少个滚动文件。按日期切分适合简单应用;高流量线上环境通常还会结合系统 logrotate 或集中式日志平台管理文件轮转。

Handler 栈和 bubbling

Monolog 的 pushHandler() 会把新 Handler 放到栈顶,因此最后添加的 Handler 最先收到记录。Handler 默认允许日志继续传给下一个 Handler,这个行为由 bubble 控制:

1$logger->pushHandler(new StreamHandler(
2    __DIR__ . '/var/log/critical.log',
3    Level::Critical,
4    bubble: false,
5));
6

bubble: false 表示当前 Handler 处理记录后停止向下传递。这个参数容易造成“某些日志怎么没写进另一个文件”的问题,配置多个 Handler 时需要一起检查级别和 bubbling。

FingersCrossedHandler:只有出错时才输出上下文

生产环境常见需求是:成功请求不必把大量调试日志写盘;一旦出现错误,把错误发生前的上下文一并落盘。FingersCrossedHandler 正是为这种场景准备的。

1use Monolog\Handler\FingersCrossedHandler;
2use Monolog\Handler\StreamHandler;
3use Monolog\Level;
4
5$nestedHandler = new StreamHandler(
6    __DIR__ . '/var/log/prod.log',
7    Level::Debug,
8);
9
10$logger->pushHandler(new FingersCrossedHandler(
11    $nestedHandler,
12    Level::Error,
13));
14

当没有达到 error 时,记录暂存在内存里;出现 error 后,缓冲区里的记录连同错误记录一起交给下层 Handler。适合保留问题前因,同时减少正常请求的日志噪声。

默认配置未必限制缓冲记录数量。长时间运行的 Worker 如果持续产生日志又长时间没有触发刷新,需要关注内存占用,并合理设置 buffer 限制或刷新策略。

Processor:给每条日志补充上下文

Processor 接收一条日志记录,可以在 Handler 输出前补充 extra 数据。Monolog 3 中,记录是 LogRecord 对象;修改后应返回新的记录对象。

1use Monolog\LogRecord;
2
3$logger->pushProcessor(static function (LogRecord $record): LogRecord {
4    return $record->with(extra: array_merge($record->extra, [
5        'pid' => getmypid(),
6        'memory_mb' => round(memory_get_usage(true) / 1024 / 1024, 2),
7    ]));
8});
9

内置 Processor 还包括:

  • PsrLogMessageProcessor:替换消息中的 {key} 占位符。
  • UidProcessor:为记录附加进程内唯一标识。
  • WebProcessor:补充请求 URI、方法和客户端 IP 等 Web 信息。
  • MemoryUsageProcessor、MemoryPeakUsageProcessor:补充内存使用数据。
  • IntrospectionProcessor:补充产生日志的文件、行号、类和方法。

Processor 可以注册到 Logger,也可以只注册到某个 Handler。请求信息 Processor 适合 Web 应用;命令行和常驻 Worker 中则要注意上下文是否会残留,尤其不能把上一个请求的用户信息带到下一条日志。

context 和 extra 的区别

应用调用时传入的数据通常放在 context:

1$logger->info('订单创建完成', [
2    'order_id' => 10086,
3    'user_id' => 42,
4]);
5

Processor 自动补充的数据通常放在 extra,比如请求 ID、PID、内存用量。两者最终都会进入 Formatter 输出,但来源和维护者不同。

记录异常时,PSR-3 约定把 Throwable 放在 exception 键中:

1try {
2    $paymentService->charge($order);
3} catch (Throwable $exception) {
4    $logger->error('扣款失败', [
5        'order_id' => $order->getId(),
6        'exception' => $exception,
7    ]);
8}
9

这样 Formatter 可以把异常类型、消息和堆栈信息写完整,而不只是记录一段错误文字。

Formatter:日志用什么格式保存?

Formatter 负责把 LogRecord 变成 Handler 最终输出的格式。常见选择:

  • LineFormatter:人类阅读方便,常用于普通文本日志。
  • JsonFormatter:结构化 JSON,适合 Loki、ELK 等日志平台采集。
  • HtmlFormatter:生成 HTML 格式,适合邮件等场景。
  • NormalizerFormatter:把对象、异常等复杂数据规范化为可序列化结构。

应用日志接入日志平台时,通常优先使用 JSON Lines:每行一个 JSON 对象,日志平台能按 order_id、request_id、level_name 等字段检索,不必再解析整段自由文本。

Symfony 项目中的 Monolog

Symfony 项目安装 MonologBundle:

1composer require symfony/monolog-bundle
2

标准环境下可在服务中注入 PSR-3 接口:

1<?php
2
3namespace App\Service;
4
5use Psr\Log\LoggerInterface;
6
7final class OrderService
8{
9    public function __construct(private LoggerInterface $logger)
10    {
11    }
12
13    public function createOrder(int $orderId): void
14    {
15        $this->logger->info('订单创建成功', [
16            'order_id' => $orderId,
17        ]);
18    }
19}
20

Symfony 默认配置通常会把 debug 及以上日志写到 var/log/dev.log,生产环境写到 var/log/prod.log。可以在 config/packages/monolog.yaml 调整 Handler:

1monolog:
2    handlers:
3        main:
4            type: fingers_crossed
5            action_level: error
6            handler: nested
7            excluded_http_codes: [404]
8            channels: ['!event']
9
10        nested:
11            type: stream
12            path: '%kernel.logs_dir%/%kernel.environment%.log'
13            level: debug
14            formatter: monolog.formatter.json
15

这个配置使用 fingers_crossed:普通日志先留在缓冲区,发生 error 后才把上下文写到文件;404 错误不触发缓冲写出;event 通道从该 Handler 排除;输出格式为 JSON。

生产环境对 404 的过滤、缓冲行为和 JSON 格式需要根据日志采集方式调整。文件路径及写权限也必须允许 PHP 运行用户访问。

按 Channel 分开记录支付日志

支付日志常常需要单独保留,避免和一般业务日志混在一起。配置 Channel 和专属 Handler:

1monolog:
2    channels: ['payment']
3
4    handlers:
5        payment:
6            type: rotating_file
7            path: '%kernel.logs_dir%/payment.log'
8            max_files: 30
9            level: info
10            channels: ['payment']
11
12        main:
13            type: fingers_crossed
14            action_level: error
15            handler: nested
16            channels: ['!event', '!payment']
17
18        nested:
19            type: stream
20            path: '%kernel.logs_dir%/%kernel.environment%.log'
21            level: debug
22

在服务中注入 monolog.logger.payment:

1use Psr\Log\LoggerInterface;
2use Symfony\Component\DependencyInjection\Attribute\Autowire;
3
4final class PaymentService
5{
6    public function __construct(
7        #[Autowire(service: 'monolog.logger.payment')]
8        private LoggerInterface $paymentLogger,
9    ) {
10    }
11
12    public function pay(int $orderId): void
13    {
14        $this->paymentLogger->info('支付请求已提交', [
15            'order_id' => $orderId,
16        ]);
17    }
18}
19

Channel 是日志来源标记,Handler 的 channels 配置决定哪些来源进入该输出。专用 Channel 适合支付、审计或第三方接口等需要单独保留和检索的场景。

Monolog 与 Symfony 事件监听器配合

如果需要记录每个 HTTP 请求的耗时,可以在 Symfony 的 kernel.response 事件中注入 LoggerInterface。这不是 Monolog 自己的事件机制,而是 Symfony EventDispatcher 调用监听器,监听器再通过 PSR-3 Logger 写日志:

1<?php
2
3namespace App\EventListener;
4
5use Psr\Log\LoggerInterface;
6use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
7use Symfony\Component\HttpKernel\Event\ResponseEvent;
8use Symfony\Component\HttpKernel\KernelEvents;
9
10#[AsEventListener(event: KernelEvents::RESPONSE)]
11final class RequestLogListener
12{
13    public function __construct(private LoggerInterface $logger)
14    {
15    }
16
17    public function __invoke(ResponseEvent $event): void
18    {
19        if (!$event->isMainRequest()) {
20            return;
21        }
22
23        $request = $event->getRequest();
24        $response = $event->getResponse();
25
26        $this->logger->info('HTTP 请求完成', [
27            'method' => $request->getMethod(),
28            'path' => $request->getPathInfo(),
29            'status_code' => $response->getStatusCode(),
30        ]);
31    }
32}
33

生产环境记录客户端 IP 前,应确认反向代理信任配置正确;日志中也应避免写入密码、Cookie、Authorization Token 等敏感信息。

日志内容的几个实用习惯

写结构化上下文,少拼长字符串

推荐:

1$logger->warning('第三方支付请求失败', [
2    'provider' => 'example-pay',
3    'order_id' => $orderId,
4    'http_status' => $statusCode,
5]);
6

这样日志平台可以直接按字段筛选。只把所有信息拼进一句话,后续检索和聚合会困难很多。

为一次请求建立关联 ID

为每个请求生成或接收一个 request_id,并让同一请求中的关键日志都携带它。排查时即可从入口日志一路追到数据库、消息队列和第三方调用。

不要记录秘密和完整凭据

密码、Session ID、Cookie、Bearer Token、支付卡数据都不应直接写入日志。必要时记录脱敏后的尾号、内部业务 ID 或失败类别。

控制日志量

debug 适合开发排查,生产环境不一定要长期全量开启。查询循环、轮询和重试逻辑里尤其要避免每次都写大量重复日志。

常见问题排查

日志文件没有生成

检查 Handler 的文件路径、运行环境、日志级别、目录是否存在,以及 PHP 进程用户是否有写权限。Symfony 项目可先查看 var/log/ 并用 php bin/console debug:config monolog 检查最终配置。

某些级别没有写出来

检查 Handler 的 level 门槛,以及多个 Handler 之间的 bubble 设置。比如 Handler 配成 error 时,info 自然不会进入该文件。

日志格式字段不符合预期

确认 Handler 关联的 Formatter;context 是调用方传入数据,extra 通常由 Processor 补充。JSON Formatter 输出的字段结构与普通 LineFormatter 不同。

Worker 运行久了内存上涨

检查是否使用了 BufferHandler 或 FingersCrossedHandler,是否有大量记录滞留缓冲区,以及 Processor 是否把大型对象塞进 context 或 extra。长生命周期进程还要避免保留请求级状态。

小结

Monolog 把日志记录拆成几个清晰环节:Logger 接收调用,Processor 补充上下文,Handler 决定输出目标和级别,Formatter 负责输出格式。Handler 可以堆叠分流;Channel 可以区分日志来源;Symfony MonologBundle 则把这些能力带入服务容器和 YAML 配置。

写日志时优先使用 PSR-3 LoggerInterface,携带可检索的结构化上下文,异常放到 exception 字段,并避免记录秘密。这样日志才能真正用于定位问题,而不只是堆在磁盘上的文本。

参考资料


参考文档


《PHP Monolog 日志实战详解:级别、Handler、Processor 与 Symfony 配置》 是转载文章,点击查看原文。


相关推荐


PHP 8.3 写 C 扩展踩坑实录:从 phpize 到 zval,一篇跑通
游鹄君2026/9/30

php扩展开发-使用 C 语言编写高性能 PHP 扩展的底层编译与调用(zval 与内存管理) 以字符串加解密为例 前提 ^ 是什么?——异或(XOR) C 里的 ^ 不是乘方,是按位异或:两个二进制位不同则 1,相同则 0 1 ^ 1 = 0 1 ^ 0 = 1 0 ^ 1 = 1 0 ^ 0 = 0 对一个字节操作时,就是 8 个 bit 逐位做这个运算。比如字符 ‘A’ 和 ‘k’: 'A' = 0x41 = 0 1 0 0 0 0 0 1 'k' = 0x6B = 0


600 元小主机怎么玩 macOS?从 U 盘、BIOS 到 UHD 630 加速和公网远程一次跑通
晨陌y2026/9/24

600 元小主机怎么玩 macOS?从 U 盘、BIOS 到 UHD 630 加速和公网远程一次跑通 前言 我一直觉得二手商用迷你主机最有意思的地方,不是“花几百块假装买到 Mac mini”,而是它给了我一块成本不高、出问题也敢继续折腾的实验平台。真正的 Mac mini 在稳定性、系统支持和整体体验上更省心,这台 HP ProDesk 600 G4 Desktop Mini 没必要去硬碰硬比较;但如果目的只是体验 macOS、录教程、做轻量桌面环境,或者顺手跑一些本地服务,那么 600


给若依加审批流,不用 Flowable
mldong2026/9/16

引言 若依是国内最流行的快速开发框架之一,GitHub 镜像 4 万多 star,几乎每个 Java 后台项目都从它起步。但它有个大家都知道的"缺口":官方免费版不内置审批流。 用若依的人,迟早要碰审批——请假、报销、合同、采购。怎么补? 这篇文章给一个不绕弯子的答案:别上 Flowable,用 jeeflow。后端一个依赖一个薄壳,前端一个宿主组件九个薄页,配一条菜单 SQL,半天跑通一个带工作台、发起、待办、审批、流程设计器的完整流程中心。 我把整个过程真机走了一遍(若依 3.9.2 mas


Elasticsearch 中的查询重写规则:通配符扫描速度提升 2.3 倍
Elasticsearch2026/9/8

作者:来自 Elastic Parker Timmins, Martijn Van Groningen 第二条规则使空字符串过滤器的速度提升了 1.6 倍。它直接从偏移数组中读取字符串长度,完全不会访问压缩后的字节。这两条规则都源于同一种习惯:运行真实查询,并寻找特殊情况。 想获得 Elastic 认证?了解下一期 Elasticsearch 工程师培训何时开课!你现在可以开始免费云试用,或者立即在你的本地机器上试用 Elastic。 Lucene 查询重写规则让 Elasticsearch


六语言引擎实现对比:同构背后的妥协与差异
mldong2026/8/31

系列定位:jeeflow 系列第 11 篇(第三季「多语言联邦」第 3 篇 · 季终) 平台:掘金(深度对比)/ 公众号(故事线) 素材版本:引擎 Java 1.8.19 / Go·Python·Node 1.8.21 / PHP 1.3.6 / Rust 1.0.6(2026-08-30 六语言同日发版) 一、先看今天发生的一件事 写这篇的时候(2026-08-30),jeeflow 刚完成一次六语言同步发版:


Linux + Docker + FastAPI 工程化实践指南
卷无止境2026/8/23

一套稳健的 FastAPI 工程,不是把 API、Redis 和 PostgreSQL 塞进同一个 Compose 文件就算完事。更合理的做法是把应用设计成无状态服务,数据库迁移、配置管理、健康检查和测试各自承担清晰职责;开发环境追求反馈速度,生产环境则强调镜像可复现、最小权限和可观测性。 下面给出一套可以直接落地的项目骨架。 一、推荐架构 开发环境可以使用 Docker Compose 编排所有依赖,代码通过挂载目录实现热更新。生产环境仍然使用相同镜像,但不再挂载源代码,也不启用 --relo


把《天龙八部》装进向量数据库:EPUB加载、文本分块与RAG问答全链路实战
浮生望2026/8/10

摘要 以《天龙八部》EPUB拆解RAG全链路:EPubLoader章节加载、RecursiveCharacterTextSplitter分块、Milvus流式入库,实现语义问答。 一、一本百万字小说,如何让AI读懂它 上一篇文章我们用AI日记助手演示了RAG的基本流程:5篇日记、手动构造数据、一次插入。但真实场景中,数据源不是手动构造的,而是各种格式的文档——PDF、EPUB、CSV、Markdown。数据量也不是5条,而是百万字级别的小说。 这篇文章以金庸的《天龙八部》EPUB电子书为样本,


前端框架vue3,vite 开发前端项目实践步骤指南
慧一居士2026/8/1

Vue 3 + Vite 前端项目实践指南 适用版本(截至 2026 年 7 月):Vue 3.5+ | Vite 6/7 | TypeScript 5.6+ | Node.js ^20.19.0 || >=22.12.0 目标:从零搭建一个可投入生产的工程化项目,覆盖「初始化 → 架构 → 规范 → 联调 → 构建部署」全流程。 全景路线图 环境准备 ──▶ 脚手架创建 ──▶ 目录规划 ──▶ Vite 配置 ──▶ 路由/状态/请求层


Java Jersey 实战指南:用 JAX-RS 注解写清晰的 REST API
唐青枫2026/7/24

简介 Jersey 是 Jakarta RESTful Web Services 规范的一种实现。 老名字常叫 JAX-RS,新包名是: jakarta.ws.rs Jersey 自己的核心包名通常是: org.glassfish.jersey 简单理解: Jakarta REST / JAX-RS 是规范 Jersey 是实现 Spring Boot 提供 Jersey 自动配置和 starter Jersey 的开发方式是用注解把 Java 类声明成 HTTP 资源: @Path("/


数据结构之双链表
无忧.芙桃2026/7/16

本篇目标: 1. 学会关于双链表的相关操作 2. 了解链表和顺序表的区别和优点 一、双链表接口实现 1. 双向链表的结构 • 单链表的结点中保存了指向后继结点的地址,所以单链表中找当前结点的后继结点很容易,但要获取当前结点的前驱结点就很麻烦,就只能从头开始往后遍历获取,时间复杂度为 O(n);所以单链表中只有当前结点的指针 pos 时(没有头指针),想要在 pos 之前插入结点和删除 pos 位置结点都是无法实现的。 • 双向链表相比单链表最大的特征是每个结点中多了一个前驱指针,

首页编辑器站点地图

本站内容在 CC BY-SA 4.0 协议下发布

Copyright © 2026 聚合阅读