PSR-3: Logger Interface

— y2sunlight 2020-04-28

本章は、若干の補足を加筆してはいるものの単にPSRのサイトを日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。

PSR-3: ロガーインターフェイス

— 原文より翻訳 PSR-3: Logger Interface 2020-04-28 現在

このドキュメントでは、ロギングライブラリの一般的なインターフェースについて説明します。

主な目標は、ライブラリが Psr\Log\LoggerInterfaceオブジェクトを受け取り、シンプルで普遍的な方法でそれにログを書き込むことを可能にすることです。カスタムニーズを持つフレームワークとCMSは、独自の目的のためにインターフェイスを拡張することができますが(MAY)、このドキュメントとの互換性を維持する必要があります (SHOULD)。これによって、アプリケーションが使用するサードパーティのライブラリが、一元化されたアプリケーションログを書き込むことが出来るようになります。

このドキュメントのキーワード MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , SHOULD NOT , RECOMMENDED , MAY 及び OPTIONAL は、 RFC 2119で説明されているように解釈して下さい。

RFC 2119の説明
MUST, REQUIRED, SHALL — 絶対必要
MUST NOT, SHALL NOT — 絶対禁止
SHOULD, RECOMMENDED — 推奨（但し、無視できる特定の正当な理由が存在するかもしれない）
SHOULD NOT — 推奨できない（但し、許可できる特定の正当な理由が存在するかもしれない）
MAY, OPTIONAL — オプション

このドキュメントの 実装者 という言葉は、LoggerInterface をログ関連のライブラリまたはフレームワークに実装する人と解釈して下さい。また、ロガーのユーザーのことは ユーザー と呼びます。

1. 仕様

1.1 基本

LoggerInterface は、ログを8つのRFC 5424レベル( debug, info, notice, warning, error, critical, alert, emergency )に書き込むための8つのメソッドを公開しています。

RFC 5424はイベント通知メッセージの伝達に使用されるsyslog Protocolについて規定されています。

9番目のメソッド log は、最初の引数としてログレベルを受け入れます。ログレベル定数の1つを使用してこのメソッドを呼び出すと、レベル固有のメソッドを呼び出す場合と同じ結果になる必要があります (MUST)。この仕様で定義されていないレベルでメソッドが呼び出された場合、実装がそのレベルを認識していない場合は、Psr\Log\InvalidArgumentException をスローする必要があります (MUST)。ユーザーは、現在の実装でサポートされていることを確認せずに、カスタムレベルを使用しないでください (SHOULD NOT)。

1.2 メッセージ

すべてのメソッドは、メッセージとして文字列、または __toString() メソッドを持つオブジェクトを受け入れます。実装者は、オブジェクトが渡された場合は特別な処理を行う場合があります (MAY)。そうでない場合は、文字列にキャストする必要があります (MUST)。

メッセージには、実装者がコンテキスト配列の値で置き換えることができるプレースホルダーが含まれる場合があります (MAY)。

プレースホルダー名は、コンテキスト配列のキーに対応している必要があります (MUST)。

プレースホルダー名は、１つの開始中括弧 { および終了中括弧 } で区切る必要があります (MUST)。区切り文字とプレースホルダー名の間に空白があってはいけません (MUST NOT)。例：{name}

プレースホルダー名は、A〜Z、a〜z、0〜9、下線( _ )、およびピリオド( . ) の文字だけで構成する必要があります (SHOULD)。

実装者は、プレースホルダーを使用して、さまざまなエスケープ方法を実装し、ログを表示用に変換できます (MAY)。ユーザはプレースホルダー値を事前にエスケープしないでください (SHOULD NOT)。というのは、データはどのコンテキストで表示されるかがわからないからです。

以下は、参照のみを目的として提供されているプレースホルダー挿入の実装例です。

<?php
 
/**
 * Interpolates context values into the message placeholders.
 * コンテキスト値をメッセージプレースホルダーに挿入する
 */
function interpolate($message, array $context = array())
{
    // build a replacement array with braces around the context keys
    // コンテキストキーを中括弧で囲む置換配列を作る
    $replace = array();
    foreach ($context as $key => $val) {
        // check that the value can be casted to string
        // 値を文字列にキャストできることを確認する
        if (!is_array($val) && (!is_object($val) || method_exists($val, '__toString'))) {
            $replace['{' . $key . '}'] = $val;
        }
    }
 
    // interpolate replacement values into the message and return
    // 置換値をメッセージに挿入して返す
    return strtr($message, $replace);
}
 
// a message with brace-delimited placeholder names
// 中括弧で区切られたプレースホルダー名を含むメッセージ
$message = "User {username} created";
 
// a context array of placeholder names => replacement values
// コンテキスト配列(プレースホルダー名=>置換値)
$context = array('username' => 'bolivar');
 
// echoes "User bolivar created"
// "User bolivar created" をエコーする
echo interpolate($message, $context);

1.3 コンテキスト

すべてのメソッドは、コンテキストデータとして配列を受け入れます。これは、文字列にうまく適合しない異質な情報(extraneous information)を保持するためのものです。配列には何でも含めることができます。実装者は、コンテキストデータをできる限り緩やかに扱う必要があります (MUST)。コンテキスト内で与えられた値によって、例外をスローしたり、php error、warning、または notice を発生させてはなりません (MUST NOT)。

Exception オブジェクトがコンテキストデータで渡される場合、それは 'exception' キーがなければなりません (MUST)。例外のロギングは一般的なパターンであり、これにより、実装者はログのバックエンドでサポートされている場合、例外からスタックトレースを抽出することができます。実装者は、何かが含まれている可能性があるため、使用する前に 'exception' キーが実際に例外であることを確認する必要があります (MUST)。

1.4 ヘルパークラスとインターフェイス

Psr\Log\AbstractLogger クラスを使用すると、LoggerInterface を拡張して一般的な log() メソッドを実装することで、LoggerInterface を非常に簡単に実装できます。他の8つのメソッドは、メッセージとコンテキストをこのlog() に転送しています。

同様に、Psr\Log\LoggerTrait を使用しても、一般的な log() メソッドを実装するだけで済みます。但し、トレイトはインターフェースを実装できないため、この場合でも LoggerInterface を実装する必要があります。

Psr\Log\NullLogger は、インターフェイスと共に提供されます。それは、ロガーが与えられていない時に、フォールバックとして「ブラックホール」実装を提供するために、インターフェイスのユーザによって使用されます (MAY)。ただし、コンテキストデータの作成にコストがかかる場合は、条件付きロギングの方が良いアプローチかもしれません。

上記の原文
The Psr\Log\NullLogger is provided together with the interface. It MAY be used by users of the interface to provide a fall-back “black hole” implementation if no logger is given to them. However, conditional logging may be a better approach if context data creation is expensive.

— 曖昧な翻訳 —
特に、最後のセンテンスの意味が良く分かりませんでした。conditional logging とは何を意味するのか? それがなぜコンテキストデータ作成と関係しているのか?

Psr\Log\LoggerAwareInterface には setLogger(LoggerInterface $logger) メソッドのみが含まれており、フレームワークが任意のインスタンスにロガーを Auto Wiring するために使用できます。

Psr\Log\LoggerAwareTrait トレイトを使用すると、LoggerAwareInterface と同等のインターフェイスを任意のクラスに簡単に実装できます。それは $this->logger へのアクセスを提供します。

Psr\Log\LogLevel クラスは、8つのログレベルの定数を保持します。

2. パッケージ

説明されているインターフェースとクラス、関連する例外クラス、および実装を検証するためのテストスイートは、psr/log パッケージの一部として提供されます。

3. Psr\Log\LoggerInterface

メソッド	要約
emergency ($message, array $context = array())	システムが使用できない
alert ($message, array $context = array())	すぐに行動を起こす必要がある
critical ($message, array $context = array())	危機的な状態
error ($message, array $context = array())	すぐに対処する必要はないが、通常はログに記録して監視する必要がある実行時エラー
warning ($message, array $context = array())	エラーではない例外的な出来事
notice ($message, array $context = array())	正常だが重要なイベント
info ($message, array $context = array())	興味深いイベント
debug ($message, array $context = array())	詳細なデバッグ情報
log($level, $message, array $context = array()	任意のレベルのロギング

LoggerInterface.php

<?php
 
namespace Psr\Log;
 
/**
 * Describes a logger instance.
 * ロガーインスタンスの説明
 *
 * The message MUST be a string or object implementing __toString().
 * メッセージは、文字列または__toString()を実装するオブジェクトでなければなりません(MUST)。
 *
 * The message MAY contain placeholders in the form: {foo} where foo
 * will be replaced by the context data in key "foo".
 * メッセージには次の形式のプレースホルダーが含まれる場合があります(MAY)：{foo}
 * この時、メッセージ内の文字列{foo}は、キーがfooのコンテキストデータに置き換えられます。
 *
 * The context array can contain arbitrary data, the only assumption that
 * can be made by implementors is that if an Exception instance is given
 * to produce a stack trace, it MUST be in a key named "exception".
 * コンテキスト配列には任意のデータを含めることができます。実装者が行うことができる唯一の仮定は、
 * スタックトレースを生成するためにExceptionインスタンスが与えられた場合、exceptionという名前の
 * キーがなければならないということです。
 *
 * See https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 * for the full interface specification.
 * 完全なインターフェース仕様については、以下を参照して下さい。
 * https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
 */
interface LoggerInterface
{
    /**
     * System is unusable.
     * システムが使用できない
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function emergency($message, array $context = array());
 
 
    /**
     * Action must be taken immediately.
     * すぐに行動を起こす必要がある
     *
     * Example: Entire website down, database unavailable, etc. This should
     * trigger the SMS alerts and wake you up.
     * 例：ウェブサイト全体がダウンしている、データベースが利用できないなど。
     * これによりSMSアラートがトリガーされ、あなたは目覚めるでしょう。
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function alert($message, array $context = array());
 
    /**
     * Critical conditions.
     * 危機的な状態
     *
     * Example: Application component unavailable, unexpected exception.
     * 例：アプリケーションコンポーネントを使用できない、予期しない例外。
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function critical($message, array $context = array());
 
    /**
     * Runtime errors that do not require immediate action but should typically
     * be logged and monitored.
     * すぐに対処する必要はないが、通常はログに記録して監視する必要がある実行時エラー
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function error($message, array $context = array());
 
    /**
     * Exceptional occurrences that are not errors.
     * エラーではない例外的な出来事
     *
     * Example: Use of deprecated APIs, poor use of an API, undesirable things
     * that are not necessarily wrong.
     * 例：廃止されたAPIの使用、APIの不適切な使用、必ずしも間違っているわけではないが望ましくないこと。
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function warning($message, array $context = array());
 
 
    /**
     * Normal but significant events.
     * 正常だが重要なイベント
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function notice($message, array $context = array());
 
    /**
     * Interesting events.
     * 興味深いイベント
     *
     * Example: User logs in, SQL logs.
     * 例：ユーザーのログイン。SQLログ。
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function info($message, array $context = array());
 
    /**
     * Detailed debug information.
     * 詳細なデバッグ情報
     *
     * @param string $message
     * @param array $context
     * @return void
     */
    public function debug($message, array $context = array());
 
    /**
     * Logs with an arbitrary level.
     * 任意のレベルのロギング
     *
     * @param mixed $level
     * @param string $message
     * @param array $context
     * @return void
     */
    public function log($level, $message, array $context = array());
}

4. Psr\Log\LoggerAwareInterface

LoggerAwareInterface.php

<?php
 
namespace Psr\Log;
 
/**
 * Describes a logger-aware instance.
 * ロガー対応インスタンスの説明
 */
interface LoggerAwareInterface
{
    /**
     * Sets a logger instance on the object.
     * オブジェクトにロガーインスタンスを設定する
     *
     * @param LoggerInterface $logger
     * @return void
     */
    public function setLogger(LoggerInterface $logger);
}

5. Psr\Log\LogLevel

LogLevel.php

<?php
 
namespace Psr\Log;
 
/**
 * Describes log levels.
 * ログレベルの説明
 */
class LogLevel
{
    const EMERGENCY = 'emergency';
    const ALERT     = 'alert';
    const CRITICAL  = 'critical';
    const ERROR     = 'error';
    const WARNING   = 'warning';
    const NOTICE    = 'notice';
    const INFO      = 'info';
    const DEBUG     = 'debug';
}

目次