Manual:Structured logging

Structured logging is operational (debug) logging that includes structured data for easier post-processing.

Starting in MediaWiki 1.25, the [https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md PSR-3 logging standard] is available for use by MediaWiki core and extensions to replace  and   debug logging calls.

The PSR-3 standard allows attaching an array of context data to each log message to provide structured key=>value pairs.

Use informative severity levels

 * 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.
 * 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.


 * 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   calls when mapped to PSR-3.
 * 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   calls when mapped to PSR-3.


 * 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.
 * 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.


 * A hard error such as a caught exception with no recovery path.
 * 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:

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  and   level messages where the wiki operator may not be familiar with the code path and needs to be able to find a good bug report.


 * If you pass an Exception object in the context parameter, it MUST be in the 'exception' key (e.g.  )


 * Record the method that emitted the error:  


 * 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   magic method if it exists).


 * 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 .


 * 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

will result in something like

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



Configuring your wiki for structured logging
For backwards compatibility, if you are using the default MediaWiki configuration and have configured 1>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  , 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 </> and <tvar|2></>.