Programmer's Reference Guide

Zend_Log

概要

Zend_Log は、ログ出力用の汎用コンポーネントです。複数のバックエンドに対応しており、ログに出力するメッセージをフォーマットしたり記録するメッセージをフィルタリングしたりすることができます。これらの関数は、以下のオブジェクトに分けられています。

ログ (Zend_Log のインスタンス) は、アプリケーション内でもっともよく使用するオブジェクトです。いくつでも望みの数だけのログオブジェクトを保持することができます。それらが互いに影響しあうことはありません。ログオブジェクトには最低ひとつのライターが含まれる必要があり、オプションでひとつあるいは複数のフィルタを含むことができます。
ライター (Zend_Log_Writer_Abstract を継承したもの) は、データを保存する役割を受け持ちます。
フィルタ (Zend_Log_Filter_Interface を実装したもの) は、保存するログデータをブロックします。フィルタは個々のライターに適用することもできますし、ログに適用することもできます。ログに適用した場合は、すべてのライターの前に適用されます。どちらの場合についても、複数のフィルタを連結することが可能です。
フォーマッタ (Zend_Log_Formatter_Interface を実装したもの) は、ログのデータをライターに書き出す前に書式設定できます。個々のライターは、それぞれひとつのフォーマッタを保持しています。

ログの作成

ログの記録を開始するには、ライターのインスタンスを作成し、それをログのインスタンスに渡します。

<?php
$logger = new Zend_Log();
$writer = new Zend_Log_Writer_Stream('php://output');

$logger->addWriter($writer);

注意すべき点は、ログには最低ひとつのライターが必要であるということです。ライターはお好みの数だけ追加することができます。追加するにはログの addWriter() メソッドを使用します。

一方、ログのコンストラクタで直接ライターを指定することも可能です。

<?php
$writer = new Zend_Log_Writer_Stream('php://output');
$logger = new Zend_Log($writer);

これで、ログが使用できるようになりました。

メッセージの記録

メッセージをログに記録するには、ログのインスタンスの log() メソッドを実行し、メッセージと優先度を渡します。

<?php
$logger->log('Informational message', Zend_Log::INFO);

log() メソッドの最初のパラメータはメッセージを表す文字列で、二番目のパラメータは優先度を表す整数値です。優先度は、ログのインスタンスが理解できる形式の値のいずれかでなければなりません。これについては次の節で説明します。

こちらも別の方法が使用できます。log() メソッドをコールするかわりに、優先度と同じ名前のメソッドをコールできます。

<?php
$logger->log('Informational message', Zend_Log::INFO);
$logger->info('Informational message');

$logger->log('Emergency message', Zend_Log::EMERG);
$logger->emerg('Emergency message');

ログの破棄

ログオブジェクトが不要になったら、ログオブジェクトを指す変数に null を代入してそれを破棄しましょう。これは、アタッチされている各ライターのインスタンスメソッド shutdown() をコールしてからログオブジェクトを破棄します。

<?php
$logger = null;

このように明示的にログを破棄することは必須ではありません。 PHP の終了時に、この処理が自動的に行われます。

組み込みの優先度の使用

Zend_Log クラスでは以下の優先度を定義しています。

EMERG   = 0;  // 緊急事態 (Emergency): システムが使用不可能です
ALERT   = 1;  // 警報 (Alert): 至急対応が必要です
CRIT    = 2;  // 危機 (Critical): 危機的な状況です
ERR     = 3;  // エラー (Error): エラーが発生しました
WARN    = 4;  // 警告 (Warning): 警告が発生しました
NOTICE  = 5;  // 注意 (Notice): 通常動作ですが、注意すべき状況です
INFO    = 6;  // 情報 (Informational): 情報メッセージ
DEBUG   = 7;  // デバッグ (Debug): デバッグメッセージ

これらの優先度は常に使用可能で、それぞれについて同じ名前のメソッドが用意されています。

これらの優先度は適当に指定しているわけではありません。もとは BSD の syslog プロトコルに由来するもので、 » RFC-3164 で示されています。それぞれの名前と優先度番号は、PHP におけるもうひとつのログ記録システムである » PEAR Log とも互換性があります。おそらく、これと Zend_Log は相互運用できるでしょう。

優先度の数値が小さいほど優先度が高くなります。EMERG (0) が最重要な優先度で、DEBUG (7) は組み込みの優先度の中ではもっとも優先度が低いものです。 DEBUG より低い優先度を定義することもできます。メッセージをログに記録する際には、この優先度の階層に注意し、適切なものを選択するようにしましょう。

ユーザ定義の優先度の追加

ユーザ定義の優先度を実行時に追加するには、ログの addPriority() メソッドを使用します。

<?php
$logger->addPriority('FOO', 8);

上の例では、新しい優先度 FOO を 8 という値で定義しています。これで、次のようにして新しい優先度でログ出力できるようになります。

<?php
$logger->log('Foo message', 8);
$logger->foo('Foo Message');

新しい優先度は、既存のものを上書きすることはできません。

ログのイベントについて理解する

log() メソッドやその仲間をコールした際に、ログのイベントが作成されます。これは単純な連想配列で、ライターに渡されるイベントの内容を表します。この配列には、 timestamp、message、priority および priorityName のキーが常に存在します。

event 配列の作成は完全に透過的です。しかし、event 配列について知っておかないと、上で示した既存のセットに含まれない項目を追加できません。

将来のイベントにたいして常に特定の項目を追加するようにするには、 setEventItem() メソッドをコールしてキーと値を指定します。

<?php
$logger->setEventItem('pid', getmypid());

上の例は、pid という名前の新しい項目を作成して現在のプロセスの PID を格納します。新しい値が設定されると、他のすべてのイベントデータと同様にすべてのライターから自動的にアクセス可能となります。項目を上書きするには、もう一度好きなときに setEventItem() メソッドをコールします。

新しいイベント項目を setEventItem() で設定すると、ロガーのすべてのライターに新しい項目を送信します。しかし、これはそれらのライターが実際にその項目を書き出すことを保証するものではありません。フォーマッタオブジェクトがその新しい項目のことを教えない限り、ライターはそれをどう扱っていいのかわからないからです。さらに詳しく学ぶには、フォーマッタの節を参照ください。

Zend_Log

Zend_Log
プログラマ向けリファレンスガイド

ライター