摘要：格式化器用來(lái)規(guī)范化并格式化輸入的記錄，以便處理器能輸出一些有用的信息。只支持使用中定義的八個(gè)級(jí)別調(diào)試信息提示警告錯(cuò)誤嚴(yán)重警報(bào)緊急來(lái)作為基本的篩選目的。警報(bào)必須立即采取行動(dòng)。這個(gè)值依賴格式化器的配置。

最近項(xiàng)目中使用的 Monolog 出了點(diǎn)小問(wèn)題，去翻其文檔，發(fā)現(xiàn)居然只有英文的。趁業(yè)余時(shí)間，翻譯一下吧。
以下是其使用說(shuō)明的中文翻譯。更多翻譯內(nèi)容見(jiàn) clarence-pan/monolog-zh-doc.

安裝

核心概念

日志級(jí)別

配置一個(gè)日志服務(wù)

為記錄添加額外的數(shù)據(jù)

使用通道

自定義日志格式

Monolog 在 Packagist (monolog/monolog) 上可用，并且可以通過(guò) Composer 安裝:

composer require monolog/monolog

如果你不使用 Composer, 那你可以從 GitHub 上獲取代碼，然后使用任何兼容 PSR-0 的自動(dòng)加載器（比如Symfony2 ClassLoader 組件）來(lái)加載 Monolog 的類

每一個(gè)日志服務(wù)實(shí)例 (Logger) 都有一個(gè)通道（名稱），并有一個(gè)處理器 (Handler)棧. 無(wú)論何時(shí)你添加一條 記錄 到對(duì)應(yīng)的日志服務(wù)實(shí)例，這個(gè)處理器棧將被遍歷一遍：每個(gè)處理器都將依次決定是否要處理這條記錄，而如果要處理，則遍歷結(jié)束（譯注：類似DOM事件冒泡）。

這樣子可以創(chuàng)建非常靈活的日志配置。比如一個(gè) StreamHandler 可以把所有日志都寫入磁盤，而上面加個(gè)MailHandler 可以把錯(cuò)誤日志作為郵件發(fā)送出去。處理器還有一個(gè) $bubble 屬性定義了是否屏蔽某條記錄或者處理了某條記錄。在這個(gè)示例中，配置 MailHandler 的 $bubble 參數(shù)為 false 則意味著 MailHandler 將不會(huì)把自己已處理過(guò)的記錄繼續(xù)冒泡給 StreamHandler.

你可以創(chuàng)建許多日志服務(wù)實(shí)例(Logger)，每一個(gè)則定義一個(gè)通道（比如數(shù)據(jù)庫(kù)、請(qǐng)求、路由...）。而每一個(gè)日志服務(wù)實(shí)例都可以組合各種各樣的處理器，可以共享處理器也可以不共享。這個(gè)通道將會(huì)在日志中反映出來(lái)，從而允許你可以很容易地查看或者篩選記錄。

每一個(gè)處理還會(huì)有一個(gè)格式化器（Formatter）。如果你沒(méi)有配置一個(gè)，則一個(gè)有意義的默認(rèn)的格式化器將被創(chuàng)建。格式化器用來(lái)規(guī)范化并格式化輸入的記錄，以便處理器能輸出一些有用的信息。

不支持自定義的嚴(yán)重性級(jí)別。只支持使用RFC 5424中定義的八個(gè)級(jí)別（調(diào)試/Debug、信息/Info、提示/Notice、警告/Warning、錯(cuò)誤/Error、嚴(yán)重/Critical、警報(bào)/Alert、緊急/Emergency）來(lái)作為基本的篩選目的。不過(guò)，如果為了排序或者其他需要靈活性的使用場(chǎng)景，你可以添加加工程序（Processor）從而可以在（處理器）處理前添加額外的信息（標(biāo)簽、用戶IP...）。

Monolog 支持一下 RFC 5424 中的日志級(jí)別：

調(diào)試/DEBUG (100): 詳細(xì)的調(diào)試信息。

信息/INFO (200): 有意義的事件，比如用戶登錄、SQL日志。

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

警告/WARNING (300): 異常事件，但是并不是錯(cuò)誤。比如使用了廢棄了的API，錯(cuò)誤地使用了一個(gè)API，以及其他不希望發(fā)生但是并非必要的錯(cuò)誤。

錯(cuò)誤/ERROR (400): 運(yùn)行時(shí)的錯(cuò)誤，不需要立即注意到，但是需要被專門記錄并監(jiān)控到。

嚴(yán)重/CRITICAL (500): 邊界條件/危篤場(chǎng)景。比如應(yīng)用組件不可用了，未預(yù)料到的異常。

警報(bào)/ALERT (550): 必須立即采取行動(dòng)。比如整個(gè)網(wǎng)站都掛了，數(shù)據(jù)庫(kù)不可用了等。這種情況應(yīng)該發(fā)送短信警報(bào)，并把你叫醒。

緊急/EMERGENCY (600): 緊急請(qǐng)求：系統(tǒng)不可用了。

這里有一個(gè)基本的配置，可以記錄日志到文件，并在 DEBUG 級(jí)別下記錄到 firephp 中:

pushHandler(new StreamHandler(__DIR__."/my_app.log", Logger::DEBUG));
$logger->pushHandler(new FirePHPHandler());

// 現(xiàn)在你就可以用日志服務(wù)了
$logger->info("My logger is now ready");

解釋一下。第一步是創(chuàng)建日志服務(wù)實(shí)例，這個(gè)實(shí)例后將在代碼中用到。唯一的參數(shù)是通道的名稱，它在你有多個(gè)日志服務(wù)實(shí)例的時(shí)候很有用。（更多詳情參見(jiàn)下面）

這個(gè)日志服務(wù)實(shí)例自己是不是知道如何處理一條日志記錄的。它把記錄代理給了一些處理器。上面的代碼中注冊(cè)了兩個(gè)處理器到棧中，以便允許使用兩種不同的方式來(lái)處理日志記錄。

注意，FirePHPHandler 是被先調(diào)用的，因而它被添加到了棧頂。這允許你臨時(shí)添加一個(gè)禁止冒泡的處理器從而允許你覆蓋其他配置的日志（處理器）。

如果你多帶帶使用 Monolog, 并且在尋找一種簡(jiǎn)單的方式來(lái)配置許多處理器，那可以用
theorchard/monolog-cascade 。
它可以幫你使用PHP數(shù)組、YAML或者JSON來(lái)構(gòu)建復(fù)雜的日志配置。

Monolog 提供了兩種不同的方式來(lái)為簡(jiǎn)單的文本消息增加額外的信息

第一種方式是使用上下文（context），這允許你在傳遞記錄的時(shí)候傳遞一個(gè)數(shù)組格式的數(shù)據(jù)：

info("Adding a new user", array("username" => "Seldaek"));

簡(jiǎn)單的處理器（比如StreamHandler）將只是把數(shù)組轉(zhuǎn)換成字符串。而復(fù)雜的處理器則可以利用上下文的優(yōu)點(diǎn)（如 FirePHP 則將以一種優(yōu)美的方式顯示數(shù)組）。

第二種方式是使用加工程序來(lái)為所有的記錄添加額外數(shù)據(jù)。加工程序可以是任何可以調(diào)用的函數(shù)。
加工程序接收日志記錄作為參數(shù)，并且需要在修改了extra字段后再返回日志記錄。讓我們來(lái)寫一個(gè)添加一些假數(shù)據(jù)的加工程序：

pushProcessor(function ($record) {
    $record["extra"]["dummy"] = "Hello world!";

    return $record;
});

Monolog提供了一些內(nèi)置的加工程序，你可以在你的項(xiàng)目中使用它們。請(qǐng)參見(jiàn)對(duì)應(yīng)的章節(jié).

小技巧：加工程序可以被注冊(cè)到一個(gè)特定的處理器上而不是直接在日志服務(wù)實(shí)例上，從而可以只在對(duì)應(yīng)的處理器上生效。

通道是一種非常棒的方式來(lái)區(qū)分是應(yīng)用的哪個(gè)部分的日志被記錄下來(lái)的。這通常在大型項(xiàng)目中非常有用（而且被Symfony2的MonologBundle所使用）。

假設(shè)有兩個(gè)日志服務(wù)實(shí)例共享了一個(gè)處理器，這個(gè)處理器將日志寫入單個(gè)日志文件。通道則將允許你來(lái)區(qū)分是哪個(gè)日志服務(wù)實(shí)例記錄了哪條日志。你可以很簡(jiǎn)單地通過(guò)通道來(lái)篩選日志。

pushHandler($stream);
$logger->pushHandler($firephp);

// 使用另外的通道來(lái)創(chuàng)建安全相關(guān)的日志服務(wù)示例
$securityLogger = new Logger("security");
$securityLogger->pushHandler($stream);
$securityLogger->pushHandler($firephp);

// 或者克隆第一個(gè)，只是改變下通道
$securityLogger = $logger->withName("security");

在Monolog中，可以很簡(jiǎn)單地來(lái)自定義日志的格式，無(wú)論是寫入文件、套接字、郵件、數(shù)據(jù)庫(kù)還是其他處理器。大多數(shù)處理器都是用 $record["formatted"] 這個(gè)值來(lái)自動(dòng)寫入日志設(shè)備。這個(gè)值依賴格式化器的配置。你可以選擇預(yù)定義的格式化器類，也可以自己寫一個(gè)（比如一個(gè)可讀的多行文本文件）。

想要配置一個(gè)預(yù)定義的格式化器類，可以直接把它設(shè)置為處理器的字段：

// 默認(rèn)的日期格式是 "Y-m-d H:i:s"
$dateFormat = "Y n j, g:i a";
// 默認(rèn)的輸出格式是 "[%datetime%] %channel%.%level_name%: %message% %context% %extra%
"
$output = "%datetime% > %level_name% > %message% %context% %extra%
";
// 最后創(chuàng)建一個(gè)格式化器
$formatter = new LineFormatter($output, $dateFormat);

// 創(chuàng)建一個(gè)處理器
$stream = new StreamHandler(__DIR__."/my_app.log", Logger::DEBUG);
$stream->setFormatter($formatter);

// 將其綁定到日志服務(wù)對(duì)象上
$securityLogger = new Logger("security");
$securityLogger->pushHandler($stream);

// 你還可以在多個(gè)處理器之間復(fù)用同一個(gè)格式化器，并且在多個(gè)日志服務(wù)實(shí)例間共享這些處理器。

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

說(shuō)明：本文首發(fā)地址：https://www.clarencep.com/201...，轉(zhuǎn)載請(qǐng)注明出處，如有翻譯得不當(dāng)之處歡迎指正。