View source for Manual:Structured logging/pl

<languages/>
{{MW 1.25|and after}}
<span lang="en" dir="ltr" class="mw-content-ltr">'''Structured logging''' is operational (debug) logging that includes structured data for easier post-processing.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">It is distinct from {{ll|Manual:Logging to Special:Log}} which is logging for the benefit of wiki editors; structured logging is for the benefit of developers.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Since MediaWiki 1.25 the [http://www.php-fig.org/psr/psr-3/ PSR-3 logging standard] has been available for use by MediaWiki core and extensions to replace the outdated <code>wfDebug</code> and <code>wfDebugLog</code> debug logging calls.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">The PSR-3 standard allows attaching an array of context data to each log message to provide structured key-value pairs.</span>

=== Get a logger from the <code>LoggerFactory</code> ===

<syntaxhighlight lang=php>
use MediaWiki\Logger\LoggerFactory;

$logger = LoggerFactory::getInstance( 'MyCoolLoggingChannel' );
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">The parameter passed to <code>LoggerFactory::getInstance</code> (here <code>MyCoolLoggingChannel</code>) is the log channel name.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">How the channel name is used depends on the logging configuration (see [[#configuring-your-wiki|below]]) but typically separate log channels can be directed to separate files or such.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You should use something unique (typically the name of your extension) as the channel name to make it easier to separate unrelated log entries.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Send log messages ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Once you have a logger object, you can use its method corresponding to PSR-3 severity levels to log messages:
</div>

; <syntaxhighlight lang=php inline>$logger->debug( 'Entered ' . __METHOD__ )</syntaxhighlight>
: <span lang="en" dir="ltr" class="mw-content-ltr">These are messages that are useful for local development and are generally too "spammy" to output on a production wiki.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This would typically include anything currently being logged via wfDebug.</span>
; <syntaxhighlight lang=php inline>$logger->info( 'Restoring page' )</syntaxhighlight>
: <span lang="en" dir="ltr" class="mw-content-ltr">Valuable state change information.</span> <span lang="en" dir="ltr" class="mw-content-ltr">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.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is currently the level automatically associated with <code>wfDebugLog</code> calls when mapped to PSR-3.</span>
; <syntaxhighlight lang=php inline>$logger->warning( 'Page is protected' )</syntaxhighlight>
: <span lang="en" dir="ltr" class="mw-content-ltr">A soft error condition such as a recoverable error or another condition that typically should not happen but isn't halting for the operation in process.</span>
; <syntaxhighlight lang=php inline>$logger->error( 'Page not found' )</syntaxhighlight>
: <span lang="en" dir="ltr" class="mw-content-ltr">A hard error such as a caught exception with no recovery path.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The PSR-3 standard includes other severity levels, however they are not recommended for usage in MediaWiki.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Add structured data to logging context ===
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
All the logging methods take an optional context array, for example:
</div>

<syntaxhighlight lang=php>
$logger->warning( 'page not found', [ 'user' => $user->getName(), 'title' => $page->getPrefixedText() ] );
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">You should add useful structured information to your log messages in this context object that others can use to find related messages or relevant database records, and trace the cause of the error.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is especially important and useful for <code>warning</code> and <code>error</code> level messages where the wiki operator may not be familiar with the code path and needs to be able to file a good bug report.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
* If you pass an Exception object in the context parameter, it MUST be in the 'exception' key (e.g. <syntaxhighlight lang=php inline>$logger->error( 'got exception', [ 'exception' => $e ] )</syntaxhighlight>)
</div> [https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md#13-context]
** <span lang="en" dir="ltr" class="mw-content-ltr">You can also generate an exception object on the fly, which is a good way of attaching a stack trace e.g. when logging an error in a utility function that's invoked in many places:</span> <syntaxhighlight lang=php inline>$logger->warning( 'called with a user which does not exist', [ 'user' => $user->getName(), 'exception' => new RuntimeException() ] )</syntaxhighlight>
<div lang="en" dir="ltr" class="mw-content-ltr">
* Attach parameters or other interesting state to messages.
</div> <span lang="en" dir="ltr" class="mw-content-ltr">It's best to make sure the items in the context array are strings.</span> <span lang="en" dir="ltr" class="mw-content-ltr">(Other types might be allowed, depending on the logging service the wiki uses, but the behavior for non-string values is often unintuitive.)</span> <span lang="en" dir="ltr" class="mw-content-ltr">Many MediaWiki core classes have a <code>__toString</code> method which generates some debugging-friendly description of the object so you can just use things like <syntaxhighlight lang=php inline>(string)$titleValue</syntaxhighlight>.</span>
** <span lang="en" dir="ltr" class="mw-content-ltr">If you do pass non-string values, try to use reasonably unique field names.</span> <span lang="en" dir="ltr" class="mw-content-ltr">This is mainly needed for Wikimedia production which sends the context data to Logstash, which requires all context data using same key to be of the same type (globally, across all log channels).</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
* Standard parameters (wiki name, server name etc) will be added automatically. Details depend on what logging service you use, but you'll probably end up using {{class doclink|MediaWiki\Logger\Monolog\WikiProcessor}}.
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
* Replace faux structure such as tab-separated items, label=value/label:value pairs, or json serialization.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
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
</div>

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

<div lang="en" dir="ltr" class="mw-content-ltr">
will result in something like
</div>

<syntaxhighlight lang="text">
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()
...
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
For maximum compatibility with various logging backends, do '''not''' use these keys in your context data:
</div>

* <code>message</code>
* <code>channel</code>
* <code>host</code>
* <code>level</code>
* <code>type</code>
* <code>@timestamp</code>
* <code>@version</code>

<div lang="en" dir="ltr" class="mw-content-ltr">
=== Use PSR-3 compatible objects ===
</div>
{{tmpl|0=<span lang="en" dir="ltr" class="mw-content-ltr">Throw exceptions which implement $1 (or, if you don't need a custom exception class, use $2) so that related exception messages can be grouped together in the logs.</span>
|1=<code>{{class doclink|class=Wikimedia\NormalizedException\INormalizedException|text=INormalizedException|type=interface|project=mediawiki-libs-NormalizedException}}</code>
|2=<code>{{class doclink|class=Wikimedia\NormalizedException\NormalizedException|text=NormalizedException|type=class|project=mediawiki-libs-NormalizedException}}</code>
}}

<span lang="en" dir="ltr" class="mw-content-ltr">You can convert Status and StatusValue objects into PSR-3 logging with:</span>

<syntaxhighlight lang="php">
$statusFormatter = MediaWikiServices::getInstance()->getFormatterFactory()->getStatusFormatter( RequestContext::getMain() );
[ $message, $context ] = $statusFormatter->getPsr3MessageAndContext( $status );
$logger->error( $message, $context );
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
This is a best effort - Status has a messy internal structure so sometimes this will just end up with something like <syntaxhighlight lang="php" inline>[ '{message}', 'message' => '...the error message in the Status object' ]</syntaxhighlight>. But for statuses holding a single message, it results in nice message strings that are easy to group.
</div>

{{anchor|configuring-your-wiki}}
<div lang="en" dir="ltr" class="mw-content-ltr">
=== Configuring your wiki for structured logging ===
</div> 
{{warning|1=<span lang="en" dir="ltr" class="mw-content-ltr">The default legacy logging implementation in MediaWiki ''drops'' most context information!</span>}}

<span lang="en" dir="ltr" class="mw-content-ltr">For backwards compatibility, if you are using the default MediaWiki configuration and have configured [[Special:MyLanguage/Manual:How to debug#Setting up a debug log file|basic logging]], then whether you supply a context object to these logger methods or to MediaWiki's global functions such as <code>wfDebugLog( 'myChannel', ''$someMessage'', 'private', ''$someContext'' )</code>, the information in the context object ''does not appear'' in the log files you've configured.</span>
<span lang="en" dir="ltr" class="mw-content-ltr">You should implement a better logger, such as [https://github.com/Seldaek/monolog monolog], as the logger "service provider interface".</span>
<span lang="en" dir="ltr" class="mw-content-ltr">See {{wg|MWLoggerDefaultSpi}} and {{ll|Manual:MonologSpi}}.</span>

<span id="See_also"></span>
== Zobacz też ==
* [[Requests for comment/Structured logging]]
* [https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md PSR-3 <span lang="en" dir="ltr" class="mw-content-ltr">logging standard</span>]
* {{ll|Manual:How to debug}}
* [[wikitech:logstash]] - <span lang="en" dir="ltr" class="mw-content-ltr">Wikimedia feeds most of its MediaWiki [[wikitech:logs|logs]] into logstash, which understands the structured logging</span>

[[Category:MediaWiki concepts{{#translation:}}]]