ロギング¶

ロギング設定¶

アプリケーションの起動処理の間に、 Log の設定は完了しているはずで config/app.php は、 これのためです。多かれ少なかれアプリケーションが望むロガーを定義できます。 ロガーは、 Cake\Log\Log を使い設定する必要があります。一例として:

use Cake\Log\Engine\FileLog;
use Cake\Log\Log;

// Classname using logger 'class' constant
Log::setConfig('info', [
    'className' => FileLog::class,
    'path' => LOGS,
    'levels' => ['info'],
    'file' => 'info',
]);

// 短いクラス名
Log::setConfig('debug', [
    'className' => 'File',
    'path' => LOGS,
    'levels' => ['notice', 'debug'],
    'file' => 'debug',
]);

// 完全な名前空間の名前
Log::setConfig('error', [
    'className' => 'Cake\Log\Engine\FileLog',
    'path' => LOGS,
    'levels' => ['warning', 'error', 'critical', 'alert', 'emergency'],
    'file' => 'error',
]);

上記では二つのロガーを作っています。一つは debug で、その他は error です。 それぞれが異なるレベルのメッセージを処理するために構成されています。 また、それらは別々のファイルにメッセージを格納しますので、 debug/notice/info のログをより深刻なエラーから分離するのが簡単です。

色々なレベルに応じた情報と意味の一覧は レベルを使う を参照してください。

一度設定を作成した後、それを変更することはできません。 Cake\Log\Log::drop() と Cake\Log\Log::setConfig() を使って、設定を削除、再作成すべきです。

それらもまた、クロージャーを与えることによりロガーを作成することが可能です。 クロージャーこれはロガーオブジェクトがどのように構築されるかを完全に制御する必要がある時に役立ちます。 クロージャーは構築されたロガーのインスタンスを返さなければなりません。例えば:

Log::setConfig('special', function () {
    return new \Cake\Log\Engine\FileLog(['path' => LOGS, 'file' => 'log']);
});

設定オプションは DSN の文字列で渡すことも可能です。これは環境変数や PaaS プロバイダーを扱っている時に役立ちます。

Log::setConfig('error', [
    'url' => 'file:///full/path/to/logs/?levels[]=warning&levels[]=error&file=error',
]);

ログエンジンの作成¶

ログエンジンはアプリケーションの一部やプラグインの一部になりえます。 例えば DatabaseLog という名前のデータベースロガーがあったとします。 アプリケーションの一部として src/Log/Engine/DatabaseLog.php に置かれます。 プラグインの一部として plugins/LoggingPack/src/Log/Engine/DatabaseLog.php に置かれます。 また、ログエンジンの設定は Cake\Log\Log::setConfig() を使う必要があります。 例えば DatabaseLog の設定はこのようになります。

// src/Log 用
Log::setConfig('otherFile', [
    'className' => 'Database',
    'model' => 'LogEntry',
    // ...
]);

// LoggingPack というプラグイン用
Log::setConfig('otherFile', [
    'className' => 'LoggingPack.Database',
    'model' => 'LogEntry',
    // ...
]);

ログエンジンを設定する時、 className パラメーターは、ログハンドラーを配置しロードするために使用されます。 その他の設定プロパティーの全ては、ログエンジンのコンストラクターに配列として渡されます。

namespace App\Log\Engine;
use Cake\Log\Engine\BaseLog;

class DatabaseLog extends BaseLog
{
    public function __construct($options = [])
    {
        parent::__construct($options);
        // ...
    }

    public function log($level, $message, array $context = [])
    {
        // データベースに書き込みます。
    }
}

CakePHP では 全てのログエンジンにおいて Psr\Log\LoggerInterface を実装する必要があります。 CakeLogEngineBaseLog クラスは、 log() メソッドを実装することだけを要求しますので、 そのインターフェイスを満たすための簡単な方法です。

use Cake\Log\Engine\SyslogLog;
use App\Log\Formatter\CustomFormatter;

// オプションのない単純なフォーマット構成
Log::setConfig('error', [
    'className' => SyslogLog::class,
    'formatter' => CustomFormatter::class,
]);

// 追加オプションを使用してフォーマッターを構成します
Log::setConfig('error', [
    'className' => SyslogLog::class,
    'formatter' => [
        'className' => CustomFormatter::class,
        'key' => 'value',
    ],
]);

エラーと例外のロギング¶

エラーと例外も記録できます。 app.php ファイル内に関連する値を設定することで ログに記録することができます。debug が true のときにエラーが表示され、debug が false のときに ログに記録されます。捕捉されなかった例外をログに記録するときは log オプションを true に設定してください。詳しくは、 構成設定 を参照ください。

ログストリームの相互作用¶

Cake\Log\Log::configured() で一連の設定を確認することができます。 configured() の戻り値は、現在設定されている全てを配列で返します。 Cake\Log\Log::drop() を使って、ストリームを削除することができます。 一度、ログの設定が削除されると、ロガーはメッセージを受信しなくなります。

FileLog アダプターの利用¶

その名前が示すように、 FileLog は、ログメッセージをファイルに書き込みます。 書かれたログメッセージのレベルは、メッセージが書き込まれたファイルの名前で決まります。 もしレベルが指定されなければ、エラーログを書き込むための LOG_ERR が使われます。 デフォルトのログの場所は logs/$level.log です。

// CakePHP クラスの中でこれを実行
$this->log("何かがうまくいかなかった！");

// logs/error.log に追記された結果
// 2007-11-02 10:22:02 Error: 何かがうまくいかなかった！

設定されたディレクトリーは、ウェブサーバーユーザー権限で正しくロギングできるように 書き込み可能にしなければなりません。

ロガーの設定により、追加/代替の FileLog の場所を設定できます。FileLog は、独自のパスを使用するために path を設定できます。

Log::setConfig('custom_path', [
    'className' => 'File',
    'path' => '/path/to/custom/place/'
]);

Syslog へのロギング¶

本番環境では、ファイルロガーの代わりに syslog を使用するようにシステムをセットアップすることを 強く勧めます。これは、(大部分は）ノンブロッキング方式で全て書き込むため、よりよく動作し、 そしてあなたのオペレーティングシステムのロガーは、独立してファイルのローテーションの設定ができ、 前処理を記述したり、ログを完全に別のストレージを使うことができます。

syslog を使うためには、デフォルトの FileLog エンジンを使うのとよく似ています。 ロギングに使用するエンジンとして Syslog を指定する必要があります。下記の設定は、デフォルトのロガーを Syslog に置き換えるものです。これは、 bootstrap.php ファイルで設定します。

Log::setConfig('default', [
    'engine' => 'Syslog'
]);

Syslog ロギングエンジンのための設定配列は、以下のキーを認識します。

• format: ２つのプレースホルダーを持つ sprintf テンプレート文字列で１つ目は、 エラーレベルで、２つ目はメッセージのためのものです。このキーは、ロギングメッセージ内の サーバーやプロセスに関する追加の情報を付加するのに便利です。例えば、 %s - Web Server 1 - %s は、プレースホルダーが置き換えられると、 error - Web Server 1 - An error occurred in this request のようになります。 このオプションは非推奨です。代わりに ロギングフォーマッタ を使用する必要があります。

• prefix: 全てのログメッセージの先頭につく文字列です。

• flag: ロガーへの接続を開くために使用される整数値のフラグで、デフォルトは、 LOG_ODELAY が使用されます。 詳しくは、 openlog のドキュメントをご覧ください。

• facility: syslog で使用するロギングスロット。デフォルトでは、 LOG_USER が使用されます。 詳しくは、 ドキュメントの syslog をご覧ください。

ログへの書き込み¶

ログファイルへの書き込みは、２つの方法があります。１つは、 静的な Cake\Log\Log::write() メソッドを使用することです。

Log::write('debug', '何かがうまくいかなかった');

２つ目は、 LogTrait を使用しているクラスに用意された log() ショートカット関数を使用することです。 log() を呼ぶと、内部的に Log::write() が呼ばれます。

// LogTrait を使用した クラス内でこれを実行
$this->log("何かがうまくいかなかった！", 'debug');

全ての設定されたログストリームは、 Cake\Log\Log::write() が呼ばれるたびに 順次書き込まれます。もし設定されていないログアダプターを持っているならば、 log() は false を返し何も書き込みません。

// すべてのレベルを受け取るように、 logs/shops.log を設定。
// スコープは `orders` と `payments` のみ
Log::setConfig('shops', [
    'className' => 'File',
    'path' => LOGS,
    'levels' => [],
    'scopes' => ['orders', 'payments'],
    'file' => 'shops.log',
]);

// すべてのレベルを受け取るように、 logs/payments.log を設定。
// スコープは `payments` のみ
Log::setConfig('payments', [
    'className' => 'File',
    'path' => LOGS,
    'levels' => [],
    'scopes' => ['payments'],
    'file' => 'payments.log',
]);

Log::warning('これは、 shops.log のみに書かれます', ['scope' => ['orders']]);
Log::warning('これは、 shops.log と payments.log の両方に書かれます', ['scope' => ['payments']]);

Log::warning('これは警告です', ['orders']);
Log::warning('これは警告です', 'payments');

Log API¶

class Cake\Log\Log¶

ログを書き込むためのシンプルなクラス。

static Cake\Log\Log::setConfig($key, $config)¶

パラメータ:

• $name (string) -- 接続されるロガーの名前で、後でロガーを削除するために使用されます。

• $config (array) -- ロガーの設定情報とコンストラクター引数の配列です。

ロガーの設定を取得したり、セットしたりします。詳細は ロギング設定 を参照してください。

static Cake\Log\Log::configured¶

戻り値:

設定されたロガーの配列です。

設定された複数のロガーの名前を取得します。

static Cake\Log\Log::drop($name)¶

パラメータ:

• $name (string) -- 今後メッセージを受信させたくないロガーの名前です。

static Cake\Log\Log::write($level, $message, $scope = [])¶

全ての設定されたロガーにメッセージを書き込みます。 $level は、作成されたログメッセージのレベルを表します。 $message は、書き込みたいログのメッセージです。 $scope は、スコープ（一つもしくは複数）でログメッセージが作成されます。

static Cake\Log\Log::levels¶

引数なしでメソッドを呼び出します。例えば、 Log::levels() は、現在のレベルの設定を取得します。

ロギングトレイト¶

trait Cake\Log\LogTrait¶

トレイトはロギングへのショートカットを提供します。

Cake\Log\LogTrait::log($msg, $level = LOG_ERR)¶

ログにメッセージを記録します。デフォルトではエラーメッセージを記録します。

Monolog を使用する¶

Monolog は、PHP で人気のロガーです。CakePHP のロガーと同じインターフェイスを実装しています。 なので、アプリケーションでデフォルトのロガーとして使うことが簡単です。

Composer を使って Monolog をインストールしたら、 Log::setConfig() メソッドを使ってロガーを設定してください。

// config/bootstrap.php

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

Log::setConfig('default', function () {
    $log = new Logger('app');
    $log->pushHandler(new StreamHandler('path/to/your/combined.log'));

    return $log;
});

// オプションで、今使っていない不要なデフォルトのロガーを止めてください
Log::drop('debug');
Log::drop('error');

もし異なるロガーをコンソールで設定したいのであれば、同じ方法を使ってください。

// config/bootstrap_cli.php

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

Log::setConfig('default', function () {
    $log = new Logger('cli');
    $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log'));

    return $log;
});

// オプションで、今使っていない不要なデフォルトの CLI ロガーを止めてください
Configure::delete('Log.debug');
Configure::delete('Log.error');