Manual:ログ記録の構造化

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Manual:Structured logging and the translation is 73% complete.

Other languages:
English • ‎français • ‎日本語
MediaWiki バージョン: 1.25

ログ記録の構造化とは運用上の(バグ修正用)ログ記録で、ポストプロセスに役立つ構造化データで構成されています。 Logging to Special:Log(Special:Logへのログ記録)と混同しないでください。

MediaWiki 1.25以降、MediaWikiコアと拡張機能ではPSR-3ログ標準を採用し、バグ修正コールのwfDebug及びwfDebugLogは廃止されました。 PSR-3 標準ではログ メッセージ単位で一連のコンテキスト データを添付でき、構造化されたキー値のペアが提供されます。

wfDebugとwfDebugLogをPSR-3に変換

LoggerFactoryからロガーを取得

use MediaWiki\Logger\LoggerFactory;

$logger = LoggerFactory::getInstance( 'MyCoolLoggingChannel' );

Where MyCoolLoggingChannel should be the name of an extension (or prefixed with the name) or one of the core logging channels.


緊急度情報の利用

$logger->debug()
ローカルの開発には便利でも、製品版ウィキに出力するには一般的に「スパムに近似」するメッセージです。 一般的に現状でwfDebugを利用してログ記録したものを網羅します。
$logger->info()
Valuable state change information. This level is a great place to record information that would be useful in a production environment when tracing the path of a request that eventually had an error. wfDebugLogコールをPSR-3標準でマッピングすると、現状では自動でこのレベルを付与します。
$logger->warning()
A soft error condition such as a recoverable error or another condition that typically should not be seen but isn't halting for the operation in process.
$logger->error()
A hard error such as a caught exception with no recovery path.

PSR-3標準に含まれる緊急度は他にもありますが、MediaWikiでの使用は非推奨です。

ログ記録コンテキストに構造化データを付加する

ログ方式に関わらず、どれも以下のようなオプションでコンテキスト オブジェクトがあります:

public function warning( $message, array $context = [] );

他の利用者が関連メッセージの検索やエラーの原因遡求に使用できるように、ログ メッセージのコンテキスト オブジェクトには有用な構造化データを付加する必要があります。 特にwarningerrorのメッセージについて、ウィキの運用者がコードパスをよく知らなくても良質なバグ報告を書くには、これが重要で有効です。

  • コンテキスト引数で例外オブジェクトを渡すには、必ず「exception」キーに書きます (例: 'exception' => $theExceptionCaught) [1]
  • エラー発生源のメソッドを記録: 'method' => __METHOD__
  • Attach parameters or other interesting state to messages. You can use objects or any other type; they will be converted to strings in a reasonable manner (e.g. using the __toString magic method if it exists).
  • 標準の引数 (ウィキ名、サーバ名など) の追加は自動処理されます。ご利用のログ記録サービスによって詳細は異なっても、結局はMediaWiki\Logger\Monolog\WikiProcessorを使うことがありえます。
  • Replace faux structure such as tab-separated items, label=value/label:value pairs, or json serialization.
  • Record stack traces by creating an exception object, adding it to the log context and then discarding it.

Many log aggregators try to deduplicate logs by message, so try to keep mutable details out of the message and move them into the context. The logger will replace any tokens inside curly braces with the corresponding value from the context. For example, the code

$logger->error( 'Caught exception while trying to create user {user}: {exception}', [
    'user' => $user->getName(),
    'exception' => $e,
] );

その出力結果の例。

Caught exception while trying to create user Foo: exception DatabaseException with message 'Unique constraint violation' in /srv/mediawiki/includes/Database.php:123
#0 /srv/mediawiki/includes/Database.php(456): Database::query()
...

さまざまなログ記録バックエンドとの互換性を最大にするため、コンテキスト データに下記のキーは使用しないでください:

  • @timestamp
  • @version
  • channel
  • host
  • level
  • type

ウィキをログの構造化用に設定する

警告 警告: The default legacy logging implementation in MediaWiki drops most context information!

For backwards compatibility, if you are using the default MediaWiki configuration and have configured basic logging, then whether you supply a context object to these logger methods or to MediaWiki's global functions such as wfDebugLog( 'myChannel', $someMessage, 'private', $someContext ), the information in the context object does not appear in the log files you've configured. monologなど、もっと質のよいログ記録器を「サービスプロバイダ・インターフェース」として採用しなければなりません。 $wgMWLoggerDefaultSpi および Manual:MonologSpi を参照してください。

関連項目