Manual:Structured logging

MediaWiki version:

≥ 1.25

Structured logging is operational (debug) logging that includes structured data for easier post-processing. It is distinct from Manual:Logging to Special:Log .

Since MediaWiki 1.25 the PSR-3 logging standard has been available for use by MediaWiki core and extensions to replace wfDebug and wfDebugLog debug logging calls. The PSR-3 standard allows attaching an array of context data to each log message to provide structured key-value pairs.

Converting wfDebug and wfDebugLog to PSR-3

Get a logger from the 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.

Use informative severity levels

$logger->debug()

These are messages that are useful for local development and are generally too "spammy" to output on a production wiki. This would typically include anything currently being logged via 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. This is currently the level automatically associated with wfDebugLog calls when mapped to 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.

The PSR-3 standard includes other severity levels, however they are not recommended for usage in MediaWiki.

Add structured data to logging context

All the logging methods take an optional context object, for example:

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

You should add useful structured information to your log messages in this context object that others can be use to find related messages and trace the cause of the error. This is especially important and useful for warning and error 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.

• If you pass an Exception object in the context parameter, it MUST be in the 'exception' key (e.g. 'exception' => $theExceptionCaught) [1]
• 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).
  • NOTE that cases have been observed where certain context elements can cause logging to silently fail. See this Phabricator ticket.
• 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 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 (e.g. 'exception' => new RuntimeException()).

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,
] );

will result in something like

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()
...

For maximum compatibility with various logging backends, do not use these keys in your context data:

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

Configuring your wiki for structured logging

Warning:

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. You should implement a better logger, such as monolog, as the logger "service provider interface". See $wgMWLoggerDefaultSpi and Manual:MonologSpi .

See also

• Requests for comment/Structured logging
• PSR-3 logging standard
• Manual:How to debug
• wikitech:logstash - Wikimedia feeds most of its MediaWiki logs into logstash, which understands the structured logging