PHP のログライブラリ 5 種を比較:Monolog、Log4php など
Monolog、Log4php、KLogger、Analog、PHP の組み込みログ機能を比較。PSR-3 の制約と JSON 出力の違いを、動く例で確認します。
PHP サービスのロガーを切り替えた直後、最初に異変が出るのはアラートかもしれない。アプリは今までどおり $logger->error() を呼んでいるのに、検索側は文字列の ERROR を探し、新しいログでは同じフィールドに数値が入っている。ログライブラリを選ぶときは、アプリが呼ぶ API と、次のシステムが読み取る出力を分けて考える。
五つの選択肢を出力で比べる
| 選択肢 | アプリから使う API | 出力と用途 |
|---|---|---|
| Monolog | PSR-3。3.12.1 は psr/log 2.x または 3.x に対応。 |
handler で出力先、processor で付加情報、formatter で形式を決められる。 |
| Apache Log4php | 独自の Logger API。 | 階層型ロガー、appender、パターンや XML のレイアウトを持つ。公式ミラーはアーカイブ済みで、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 や OS がどこに出すか分かっているスクリプトや実行環境の調査に使える。 |
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 では、8 段階のレベルと context 配列を使える。例外をロガーに渡すときは exception キーに入れる。呼び出し側は共通化できるが、JSON の項目名、保存先、ローテーション、保持期間は実装と運用設定で決まる。PHP-FIG の PSR-3(英語)
Laravel の場合は config/logging.php のチャンネルを見る。基盤は Monolog だが、実際に使われる handler と形式はチャンネルで決まる。Symfony には簡易な PSR-3 ロガーがあり、Monolog を使うには MonologBundle を導入する。handler を調べる前に、どちらが動いているか確かめる。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 ワーカーを使う。ローカルの出力を収集側が転送すれば、リクエスト処理からそのネットワーク通信を切り離せる。書き込み負荷が高いとローカル出力でも待ちが発生する。バッファーを使うなら、いつまとめて送るかと、異常終了時にどこまで失うかを把握する。日付付きのファイル名にするだけでは古いログは消えない。
