PHP 日誌套件怎麼選?比較 Monolog、Log4php 與另外三種方案
比較 Monolog、Log4php、KLogger、Analog 和 PHP 原生日誌,核對 PSR-3 版本、輸出去向與更換套件時的 JSON 欄位。
PHP 服務換了日誌套件,最先露出異常的可能是告警突然安靜。程式仍然呼叫 $logger->error(),原本的查詢卻在數值欄位裡找字串 ERROR。選擇 PHP 日誌套件時,要一起考慮程式呼叫的介面,以及下游實際讀到的輸出。
從輸出方式比較五種方案
| 方案 | 程式使用的介面 | 輸出與用途 |
|---|---|---|
| Monolog | PSR-3。3.12.1 支援 psr/log 2.x 或 3.x。 |
handler 決定目的地,processor 補上共用欄位,formatter 決定格式。 |
| Apache Log4php | 自有 Logger API。 | 有階層式 logger、appender,以及樣式和 XML 版面配置。Apache 鏡像已封存,Composer 套件標記為停止維護。 |
| KLogger | 2022 年發佈的 1.2.2 依賴 psr/log 1.x。 |
寫入文字檔。可設定等級門檻和格式,預設檔名包含日期。 |
| Analog | 靜態 API 和 PSR-3 包裝器 Analog\Logger。2023 年的穩定版 1.0.21 依賴 psr/log 3.x。 |
由內建或自訂閉包 handler 決定目的地與格式。 |
PHP error_log() / syslog() |
參數不同的原生函式。 | 已知 PHP 或系統日誌去向時,可用於小型指令稿或執行環境診斷。 |
Composer 的版本限制也要看。已使用 Monolog 3 和 psr/log 3.x 的專案,無法把 KLogger 1.2.2 加進同一組依賴。Analog 的包裝器相容 3.x,輸出仍由 handler 決定。若在維護 Log4php,搬移呼叫之前先盤點現有 appender、等級門檻與版面配置。Monolog 套件 · KLogger 套件 · Analog 套件 · Apache Log4php 套件
查清楚目前的日誌去向
PSR-3 的 Psr\Log\LoggerInterface 提供八種等級和 context 陣列。若希望 logger 處理例外,可透過 exception 鍵傳入。程式呼叫可以沿用同一套介面,JSON 欄位、儲存目的地、檔案輪替和保留期限則由實作和部署設定決定。PHP-FIG PSR-3(英文)
Laravel 從 config/logging.php 的 channel 著手。底層用 Monolog,實際 handler 和格式由 channel 決定。Symfony 自帶簡易 PSR-3 logger,也能安裝 MonologBundle 接上 Monolog。要檢查 handler 設定之前,先確認目前跑的是哪種 logger。Laravel 日誌(英文) · Symfony 日誌(英文)
小型 CLI 指令稿可能只需要 error_log($message)。預設類型 0 按 PHP 錯誤日誌設定送出,回傳值不能證明已寫入。類型 3 會附加到指定檔案,也要自行加換行。syslog(LOG_ERR, $message) 可傳送優先等級給系統日誌。Web 服務則應分開查 PHP 引擎錯誤和應用程式日誌,SAPI、程序與框架的路徑可能不同。PHP error_log(英文) · PHP syslog(英文) · PHP 錯誤設定(英文)
先用新的格式化器輸出一筆事件
在裝有 PHP 8.1 以上版本的空白測試目錄,執行 composer require monolog/monolog:3.12.1。把下面範例存成 checkout.php,再執行 php checkout.php。呼叫端接收 PSR-3 介面,handler 和 formatter 決定標準輸出會收到什麼。
<?php
require __DIR__ . '/vendor/autoload.php';
use Monolog\Formatter\JsonFormatter;
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use Psr\Log\LoggerInterface;
function reportCheckoutFailure(LoggerInterface $logger): void
{
$logger->error('Checkout failed', [
'event' => 'checkout_failed',
'request_id' => 'fixture-42',
'exception' => new RuntimeException('Synthetic failure'),
]);
}
$handler = new StreamHandler('php://stdout');
$handler->setFormatter(new JsonFormatter());
$logger = new Logger('checkout', [$handler]);
reportCheckoutFailure($logger);
用固定版本執行時得到一行 JSON。數值 level 是 400,字串 level_name 是 ERROR。例外在 context.exception,datetime 帶有時區位移。既有查詢若依賴舊欄位或巢狀層級,就要依實際輸出調整。Monolog JsonFormatter
切換前,先取實際應用程式的一筆正常記錄和一筆例外記錄。若 DataKit 收集檔案或容器輸出,請看 Pipeline 解析後的欄位,再用兩筆樣本核對既有錯誤查詢。應用程式的請求 ID 和 trace ID 要分開,兩種格式都別寫入權杖或個人資料。DataKit 日誌收集(簡體中文)
確認目的地變慢時會怎麼處理
同步網路 handler 等候對端回應時,仍會占用 PHP-FPM 工作程序。把資料先寫到本機再交由收集器轉送,可以將這段網路傳輸移出請求處理。本機寫入遇到壓力也可能卡住。採用緩衝時,要確認何時批次送出,以及異常結束時會遺失多少資料。檔名帶日期也不代表舊檔會自動刪除。
