PHP项目Monolog日志库深度指南：从入门到生产级配置
目录导读
- 为什么选择Monolog？
- 安装与核心概念
- 基础使用：日志通道与处理器
- 进阶技巧：日志格式化与上下文数据
- 生产级配置：文件轮转与错误级别
- 常见问答：性能优化与问题排查
内容
为什么选择Monolog？
在PHP项目中,日志系统是调试和监控的“眼睛”，Monolog是目前最流行的日志库，被Symfony、Laravel等主流框架内置集成，它支持多种日志处理器（如文件、数据库、邮件、Slack），并允许自定义格式。
核心优势：
- 轻量级,不强制绑定框架
- 支持PSR-3日志接口标准
- 可通过处理器链实现分级日志输出（错误日志直接发送邮件，INFO日志写入文件）
安装与核心概念
安装（Composer）：
composer require monolog/monolog
三个核心组件：
- Logger：日志记录器，负责调用方法（如
->info()、->error()） - Handler：处理器，定义日志去向（文件、数据库等）
- Formatter：格式化器，控制日志输出格式（JSON、行格式等）
快速示例：
use Monolog\Logger;
use Monolog\Handler\StreamHandler;
$log = new Logger('app');
$log->pushHandler(new StreamHandler(__DIR__.'/logs/app.log', Logger::WARNING));
$log->warning('内存使用过高', ['memory' => memory_get_usage()]);
// 输出：包含时间戳、级别、通道和上下文数组
基础使用：日志通道与处理器
多通道分离日志：
// 创建两个日志通道
$appLog = new Logger('app');
$errorLog = new Logger('error');
$appLog->pushHandler(new StreamHandler('app.log', Logger::INFO));
$errorLog->pushHandler(new StreamHandler('error.log', Logger::ERROR));
$appLog->info('用户登录成功', ['user_id' => 123]);
$errorLog->error('数据库连接失败');
常用处理器：
StreamHandler：写入文件或流RotatingFileHandler：日/月自动轮转文件（推荐生产环境）SlackWebhookHandler：发送到Slack群组FirePHPHandler：调试时实时输出到浏览器控制台
处理器优先级：
通过 pushHandler 添加的处理器会按添加顺序执行，若需不同日志级别分配到不同处理器，可设置 $logLevel 参数。
进阶技巧：日志格式化与上下文数据
自定义格式（JSON格式）：
use Monolog\Formatter\JsonFormatter;
$handler = new StreamHandler('app.json', Logger::INFO);
$handler->setFormatter(new JsonFormatter());
$log->pushHandler($handler);
$log->info('用户操作', ['action' => 'purchase', 'amount' => 99.9]);
// 输出：{"message":"用户操作","context":{"action":"purchase","amount":99.9},"level":200,"channel":"app","datetime":"2025-03-20T10:30:00+08:00"}
上下文数据（Context）：
始终将动态数据（如用户ID、IP、请求参数）放在第二个参数中，而非直接拼接到消息字符串，这样便于后续日志分析系统（如ELK）索引。
错误级别映射表：
| 级别 | 方法 | 场景 |
|------|------|------|
| DEBUG | ->debug() | 开发调试 |
| INFO | ->info() | 系统正常运行信息 |
| ERROR | ->error() | 需要人工干预的异常 |
| CRITICAL | ->critical() | 系统不可用 |
生产级配置：文件轮转与错误级别
按日期轮转文件：
use Monolog\Handler\RotatingFileHandler; $handler = new RotatingFileHandler(__DIR__.'/logs/app.log', 30, Logger::ERROR); $log->pushHandler($handler); // 自动生成 app-2025-03-20.log，保留最近30天日志
分离敏感级别：
$log = new Logger('production');
$log->pushHandler(new StreamHandler('info.log', Logger::INFO));
$log->pushHandler(new StreamHandler('critical.log', Logger::CRITICAL));
// info.log 包含 INFO 及以上级别（不含DEBUG），critical.log 只记录CRITICAL级别
性能优化建议：
- 避免在循环中创建Logger实例（应复用单例）
- 延迟加载处理器：使用
$handler->pushProcessor()插入处理逻辑前先判断级别 - 生产环境禁用
BrowserConsoleHandler
常见问答：性能优化与问题排查
Q1：Monolog会影响PHP性能吗？
A：合理配置下影响极小，建议：
- 使用
RotatingFileHandler替代StreamHandler写入单个文件 - 避免写入远程服务（如Slack）时阻塞请求，可通过队列异步处理
Q2：如何避免日志文件无限变大？
A：使用 RotatingFileHandler 并设置保留天数（如30天），或搭配Linux logrotate工具。
Q3：如何将日志发送到远程日志服务（如Logstash）？
A：使用 SocketHandler 发送TCP/UDP，或配合 JsonFormatter 输出结构化JSON，再由Filebeat等工具采集。
Q4：遇到日志丢失怎么办？
A：检查：
- 文件目录是否可写
- 处理器级别是否正确（如
Logger::ERROR不会记录WARNING） - 清理PHP错误日志确认无权限问题
Q5：如何自定义日志格式？
A：继承 LineFormatter 并重写 format() 方法，或直接使用 %channel%、%level_name% 等占位符：
$formatter = new LineFormatter("%datetime% [%level_name%] %message% %context%\n");
$handler->setFormatter($formatter);
Monolog通过灵活的处理器链和格式化机制,能覆盖从开发调试到生产监控的完整日志需求，建议根据业务规模：小型项目用 StreamHandler + LineFormatter，中大型项目用 RotatingFileHandler + JsonFormatter 配合日志分析系统，掌握这些用法后，你的PHP项目日志将不再是一堆混乱的文本，而是可检索、可告警的“数据库”。
