WooCommerce 2.7 でのログ取得の改善

この記事は WooCommerce 開発者ブログの「Improved logging in WooCommerce 2.7」を日本語訳したものです。
※こちらの日本語の記事では「ロガー(logger)」を「ログ取得システム」と意味が少し分かりやすくするために意訳しています。システムに慣れている方はお手数ですが、「ロガー」に置き換えてお考えください。「ロガー」の方がシステム屋にはスムーズに入ってくると思います。

ここから ===============

2.7 の変更の1つは、改善されたログ取得システムです。私たちは、拡張性を重視してログ取得システムの限界に取り組むためにかなりの努力をしました。この記事では、作成された変更点と、次のバージョン 2.7 ベータ版から新しいログ取得システムを利用する方法を概説します。みてみましょう…

変更点

我々は、ログ出力ハンドラの概念を導入しました。この変更により、ログ取得システム自体のログの処理方法が抽出されます。コアの WC_Logger は引き続きログメッセージを受信しますが、動作を設定された登録済みのハンドラにログを渡すだけです。これにより、ログ取得システムの交換を必要とせずにログ取得システムの動作を簡単に変更することができます。

wc_get_logger 関数は、共有されたログ取得システムインスタンスに返すために導入されました。サイト全体のログ取得システムのインスタンスを取得するには、$logger = wc_get_logger（）を呼び出します。

WC_Loggerのコアは、ハンドラを扱うために大幅に書き直されました。また、PSR-3 ログ取得システムインタフェースで記述されたメソッドも実装しています。 PSR-3 はログ取得システムインターフェースの標準仕様であるため、これを実装することで、交換用ログ取得システムを簡単に見つけることができ、他のPSR-3互換ログ取得システムの経験があれば使い慣れたものになります。

新しい WC_Logger

ログ取得システムと対話する好ましい方法は、wc_get_logger を介してログ取得システムを取得し、次のようにロギング・メソッドの1つを呼び出すことです。

$logger = wc_get_logger();

// $context は任意のデータを保持するかもしれません。
// "source"を指定すると、ログがグループ化されます。
// これについては後で詳しく説明します。
$context = array( 'source' => 'my-extension-name' );

$logger->debug( 'Detailed debug information', $context );
$logger->info( 'Interesting events', $context );
$logger->notice( 'Normal but significant events', $context );
$logger->warning( 'Exceptional occurrences that are not errors', $context );
$logger->error( 'Runtime errors that do not require immediate', $context );
$logger->critical( 'Critical conditions', $context );
$logger->alert( 'Action must be taken immediately', $context );
$logger->emergency( 'System is unusable', $context );

// `log` メソッドは、有効なレベルを最初の引数として受け取ります。
$logger->log( 'debug', '<- Provide a level', $context );

ログレベル

メソッドの debug、info、…、emergency はレベルであり、すべてのログメッセージにレベルが含まれていなければなりません。ログメッセージの重大度をdebugからemergency、最低から最高まで表示します。それらは IEFT RFC5424 仕様書に記述されています：

Emergency: システムは使用できません
Alert: すぐに行動を取らなければならない
Critical: 重大な状態
Error: エラー状況
Warning: 警告状況
Notice: 正常だが重大な状態
Informational: 情報通知
Debug: デバッグレベル通知

一つの投稿で説明するには量が多すぎるので、皆さん別に勉強してみてね。

ログ取得システムメソッド

8つの「レベル」メソッドに加えて、logメソッドは最初の引数として任意のレベルを受け取ります。$logger->log( 'info', 'An "info" level message.' );

すべてのメソッド（addを除く）は、最後の引数としてコンテキスト配列も受け入れます。コンテキストは、ログを扱うときに使用される任意の情報の配列です。コアハンドラにログメッセージをグループ化させるために、コンテキストにsourceを含めます。

// 次のメッセージはまとめてグループ化されます
$logger->debug( 'debug message', array( 'source' => 'my-extension' ) );
$logger->info( 'another message', array( 'source' => 'my-extension' ) );

WC_Loggerでは引き続きaddメソッドが公開されていますが、下位互換性のためにのみ使用されます。 addは PSR-3 仕様の一部ではなく、2.7で廃止しないことにしましたが、将来廃止され、削除される可能性が高くなります。 PSR-3 対応のメソッドへの追加呼び出しを更新する方法は次のとおりです。

// 以前
$logger->add( 'my-extension', 'The log message' );
// これから (最も適切なレベルを選択)
$logger->info( 'The log message', array( 'source' => 'my-extension' ) );

ログ取得システムの交換

提供されたログ取得システムを交換する場合は、 woocommerce_logging_class フィルターを使用してください。このフィルタは、wc_get_loggerから返された共有されたログ取得システムインスタンスに影響し、WC_Logger_Interfaceを実装するクラス名またはインスタンスを返す必要があります。このインターフェースは2.7で新しくなっており、代替ログ取得システムが WooCommerce のエコシステム全体のログ記録に互換性があることを保証するのに役立ちます。

function return_my_logger() { return 'My_Compatible_Logger_Class'; }
add_filter( 'woocommerce_logging_class', 'return_my_logger' );

// $logger は My_Compatible_Logger_Class のインスタンスになります。
$logger = wc_get_logger();

wc_get_loggerは共有インスタンスを返すので、wc_get_loggerを最初に呼び出す前にフィルタを登録して、何らかの効果を持たせる必要があります。

WC_Logger_Interface には、 PSR-3 で説明されているすべてのメソッドと、下位互換性を維持するためのaddメソッドが含まれています。 WC_Logger_Interface を実装するには、 PSR-3 ログ取得システムもaddメソッドを実装する必要があります。

ログハンドラ

ログハンドラはコアのログ取得システムの動作をカスタマイズするための 2.7 のソリューションです。 WC_Logger は、ハンドラの配列を保持し、それぞれにログメッセージを渡すことによって、すべての作業をハンドラに委譲します。コアには、いくつかのハンドラが用意されています。

ファイル

WC_Log_Handler_Fileは、ログをファイルに書き込みます。ファイルは、WooCommerce の管理ステータスページまたはwp-content/uploads/wc-logs/のサーバー上で表示できます。ファイルの処理は、以前のログ取得システムの振る舞いと本質的に同じです。

データベース

WC_Log_Handler_DB はデータベースにログを書き込みますが、管理領域からログを直接表示、フィルタリング、ソートする場合は非常に便利です。それは、 WooCommerce の管理ステータスページに光沢のある新しいインターフェイスが付属しています。確認してください：

設定構成

WooCommerce はデフォルトで WC_LOG_HANDLER 定数で設定できるハンドラを登録するので、これを wp-config.php に追加してDBログ取得システムを使用することができます：

define( 'WC_LOG_HANDLER', 'WC_Log_Handler_DB' );

この定数は、ログハンドラクラスの名前でなければなりません。これは、 WooCommerce の管理ステータスページでデフォルトのハンドラとビューアを決定するので、コアハンドラの1つを使用することをお勧めします。

より多くのハンドラを登録する場合は、 woocommerce_register_log_handlers フィルタを使用してインスタンス化されたハンドラの配列を返す必要があります。

function add_my_handler( $handlers ) {
    array_push( $handlers, new My_Log_Handler() );
    return $handlers;
}
add_filter( 'woocommerce_register_log_handlers', 'add_my_handler' );

ハンドラの実装

使用可能なハンドラは、コアに含まれているものだけです。これにより、ログハンドラは拡張のための絶好の機会になります。ハンドラが実装する必要がある唯一のメソッドは handle です。2.7にはハンドラを実装するために拡張できる抽象 WC_Log_Handler クラスが含まれています。

WC_Log_Handler_File および WC_Log_Handler_DB に加えて、コアには WC_Log_Handler_Email が含まれます。電子メールハンドラは完全に機能していますが、電子メールは一般的にログを処理するための非常に優れたシステムではありませんので、重要な制作サイトで使用することはお勧めしません。私が実装するかもしれない他のハンドラや、どうやってそれをどうやって動くかについてのアイデアを探すのは素晴らしいリソースだと思います。

ハンドラの実装はおそらく次のようになります。

class My_New_Handler extends WC_Log_Handler {
    public function handle( $timestamp, $level, $message, $context ) {
        // メッセージで面白い何かを...
    }
}

注意：ハンドラは、 handle メソッドを含む WC_Log_Handler_Interface を実装する必要があります。 WC_Log_Handler を拡張すると、これはすでに処理されています。ただし、拡張せずにハンドラを実装する場合は、 WC_Log_Handler_Interface が実装されていることを確認してください。

変更がプラグイン/拡張機能/サイトを壊す可能性がありますか？

それはないでしょう！新しい機能に興味がない場合、コードは以前と変わりなく機能し続けます。私たちは、ログ取得システムが後方互換性を保つように最善を尽くしました。つまり、 $logger->add（） はPSR-3仕様の一部ではなく、2.7で廃止されませんが、今後廃止または廃止される可能性があります。新しいメソッドの1つを使用するようにログ呼び出しを更新することをお勧めします。

いつ始めることができますか？

これらの変更は現在マスターであるため、いつでも最新のテストを開始できます。新しいロガーは、次の 2.7 ベータ版の一部になる予定です。

おまけ

そうです、もっとあります！ print_r のようなデバッグ機能をブラックリストに載せた非常に厳しいサーバー環境を見てきました。これはロギングとデバッグを複雑にする可能性があり、print_r を呼び出そうとすると致命的なエラーが発生する可能性があります。この問題を解決するために、 2.7 のコアの一部である wc_print_r を導入しました。 print_rの代わりに考えられます：

wc_print_r( array( 1, 2, 3 ) );

上が下に。

Array
(
    [0] => 1
    [1] => 2
    [2] => 3
)

文字列表現を返す場合は、 print_r のように2番目の引数として true を指定します。

$logger->alert( wc_print_r( $myvar, true ) );

問題を見つけたら？

いつものように、WooCommerceでの問題の登録ページで問題をログにしていってください。ハッピーロギング！（造語）

ここまで=======

変更点