【翻译】Monolog使用说明

前言

最近项目中使用的 Monolog 出了点小问题，去翻其文档，发现竟然只有英文的。趁业余时间，翻译一下吧。
如下是其使用说明的中文翻译。更多翻译内容见 clarence-pan/monolog-zh-doc.

使用 Monolog

• 安装

• 核心概念

• 日志级别

• 配置一个日志服务

• 为记录添加额外的数据

• 使用通道

• 自定义日志格式

<!-- more -->

安装

Monolog 在 Packagist (monolog/monolog) 上可用，而且能够经过 Composer 安装:

composer require monolog/monolog

若是你不使用 Composer, 那你能够从 GitHub 上获取代码，而后使用任何兼容 PSR-0 的自动加载器（好比Symfony2 ClassLoader 组件）来加载 Monolog 的类

核心概念

每个日志服务实例 (Logger) 都有一个通道（名称），并有一个处理器 (Handler)栈. 不管什么时候你添加一条 记录 到对应的日志服务实例，这个处理器栈将被遍历一遍：每一个处理器都将依次决定是否要处理这条记录，而若是要处理，则遍历结束（译注：相似DOM事件冒泡）。

这样子能够建立很是灵活的日志配置。好比一个 StreamHandler 能够把全部日志都写入磁盘，而上面加个MailHandler 能够把错误日志做为邮件发送出去。处理器还有一个 $bubble 属性定义了是否屏蔽某条记录或者处理了某条记录。在这个示例中，配置 MailHandler 的 $bubble 参数为 false 则意味着 MailHandler 将不会把本身已处理过的记录继续冒泡给 StreamHandler.

你能够建立许多日志服务实例(Logger)，每个则定义一个通道（好比数据库、请求、路由...）。而每个日志服务实例均可以组合各类各样的处理器，能够共享处理器也能够不共享。这个通道将会在日志中反映出来，从而容许你能够很容易地查看或者筛选记录。

每个处理还会有一个格式化器（Formatter）。若是你没有配置一个，则一个有意义的默认的格式化器将被建立。格式化器用来规范化并格式化输入的记录，以便处理器能输出一些有用的信息。

不支持自定义的严重性级别。只支持使用RFC 5424中定义的八个级别（调试/Debug、信息/Info、提示/Notice、警告/Warning、错误/Error、严重/Critical、警报/Alert、紧急/Emergency）来做为基本的筛选目的。不过，若是为了排序或者其余须要灵活性的使用场景，你能够添加加工程序（Processor）从而能够在（处理器）处理前添加额外的信息（标签、用户IP...）。

日志级别

Monolog 支持一下 RFC 5424 中的日志级别：

• 调试/DEBUG (100): 详细的调试信息。

• 信息/INFO (200): 有意义的事件，好比用户登陆、SQL日志。

• 提示/NOTICE (250): 正常可是值得注意的事件。

• 警告/WARNING (300): 异常事件，可是并非错误。好比使用了废弃了的API，错误地使用了一个API，以及其余不但愿发生可是并不是必要的错误。

• 错误/ERROR (400): 运行时的错误，不须要当即注意到，可是须要被专门记录并监控到。

• 严重/CRITICAL (500): 边界条件/危笃场景。好比应用组件不可用了，未预料到的异常。

• 警报/ALERT (550): 必须当即采起行动。好比整个网站都挂了，数据库不可用了等。这种状况应该发送短信警报，并把你叫醒。

• 紧急/EMERGENCY (600): 紧急请求：系统不可用了。

配置一个日志服务

这里有一个基本的配置，能够记录日志到文件，并在 DEBUG 级别下记录到 firephp 中:

<?php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\FirePHPHandler;

// 建立日志服务
$logger = new Logger('my_logger');

// 添加一些处理器
$logger->pushHandler(new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG));
$logger->pushHandler(new FirePHPHandler());

// 如今你就能够用日志服务了
$logger->info('My logger is now ready');

解释一下。第一步是建立日志服务实例，这个实例后将在代码中用到。惟一的参数是通道的名称，它在你有多个日志服务实例的时候颇有用。（更多详情参见下面）

这个日志服务实例本身是否是知道如何处理一条日志记录的。它把记录代理给了一些处理器。上面的代码中注册了两个处理器到栈中，以便容许使用两种不一样的方式来处理日志记录。

注意，FirePHPHandler 是被先调用的，于是它被添加到了栈顶。这容许你临时添加一个禁止冒泡的处理器从而容许你覆盖其余配置的日志（处理器）。

若是你单独使用 Monolog, 而且在寻找一种简单的方式来配置许多处理器，那能够用
theorchard/monolog-cascade 。
它能够帮你使用PHP数组、YAML或者JSON来构建复杂的日志配置。

为记录添加额外的数据

Monolog 提供了两种不一样的方式来为简单的文本消息增长额外的信息

使用上下文(context)

第一种方式是使用上下文（context），这容许你在传递记录的时候传递一个数组格式的数据：

<?php

$logger->info('Adding a new user', array('username' => 'Seldaek'));

简单的处理器（好比StreamHandler）将只是把数组转换成字符串。而复杂的处理器则能够利用上下文的优势（如 FirePHP 则将以一种优美的方式显示数组）。

使用加工程序(Processor)

第二种方式是使用加工程序来为全部的记录添加额外数据。加工程序能够是任何能够调用的函数。
加工程序接收日志记录做为参数，而且须要在修改了extra字段后再返回日志记录。让咱们来写一个添加一些假数据的加工程序：

<?php

$logger->pushProcessor(function ($record) {
    $record['extra']['dummy'] = 'Hello world!';

    return $record;
});

Monolog提供了一些内置的加工程序，你能够在你的项目中使用它们。请参见对应的章节.

小技巧：加工程序能够被注册到一个特定的处理器上而不是直接在日志服务实例上，从而能够只在对应的处理器上生效。

使用通道

通道是一种很是棒的方式来区分是应用的哪一个部分的日志被记录下来的。这一般在大型项目中很是有用（并且被Symfony2的MonologBundle所使用）。

假设有两个日志服务实例共享了一个处理器，这个处理器将日志写入单个日志文件。通道则将容许你来区分是哪一个日志服务实例记录了哪条日志。你能够很简单地经过通道来筛选日志。

<?php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\FirePHPHandler;

// 建立一些处理器
$stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
$firephp = new FirePHPHandler();

// 建立应用的主要日志服务实例
$logger = new Logger('my_logger');
$logger->pushHandler($stream);
$logger->pushHandler($firephp);

// 使用另外的通道来建立安全相关的日志服务示例
$securityLogger = new Logger('security');
$securityLogger->pushHandler($stream);
$securityLogger->pushHandler($firephp);

// 或者克隆第一个，只是改变下通道
$securityLogger = $logger->withName('security');

自定义日志格式

在Monolog中，能够很简单地来自定义日志的格式，不管是写入文件、套接字、邮件、数据库仍是其余处理器。大多数处理器都是用 $record['formatted'] 这个值来自动写入日志设备。这个值依赖格式化器的配置。你能够选择预约义的格式化器类，也能够本身写一个（好比一个可读的多行文本文件）。

想要配置一个预约义的格式化器类，能够直接把它设置为处理器的字段：

// 默认的日期格式是 "Y-m-d H:i:s"
$dateFormat = "Y n j, g:i a";
// 默认的输出格式是 "[%datetime%] %channel%.%level_name%: %message% %context% %extra%\n"
$output = "%datetime% > %level_name% > %message% %context% %extra%\n";
// 最后建立一个格式化器
$formatter = new LineFormatter($output, $dateFormat);

// 建立一个处理器
$stream = new StreamHandler(__DIR__.'/my_app.log', Logger::DEBUG);
$stream->setFormatter($formatter);

// 将其绑定到日志服务对象上
$securityLogger = new Logger('security');
$securityLogger->pushHandler($stream);

// 你还能够在多个处理器之间复用同一个格式化器，而且在多个日志服务实例间共享这些处理器。

处理器、格式化器和加工程序 →

---

说明：本文首发地址：https://www.clarencep.com/201...，转载请注明出处，若有翻译得不当之处欢迎指正。