Manual:MonologSpi.php
| MediaWiki file: MonologSpi.php | |
|---|---|
| Location: | includes/debug/logger/ |
| Source code: | master • 1.42.3 • 1.41.4 • 1.39.10 |
| Classes: | MonologSpi |
MediaWiki\Logger\MonologSpi is a service provider interface for use with $wgMWLoggerDefaultSpi that creates Monolog loggers. MonologSpi enables Structured logging, which means you can record an arbitrary array of data with your log events instead of just a string.
Details
[edit]Monolog allows a large amount of flexibility in configuring the destination, format and contents of log events. The basic building blocks of a Monolog configuration are:
$wgMWLoggerDefaultSpi = [
'class' => \MediaWiki\Logger\MonologSpi::class,
'args' => [ [
'loggers' => [
'@default' => [ /* Template for any log channel without explicit config */ ],
'some-special-log-channel' => [ /*...*/ ],
],
'processors' => [ /*...*/ ],
'handlers' => [ /*...*/ ],
'formatters' => [ /*...*/ ],
] ],
];
- Loggers
- A logger is a named logging channel. The name of the channel is used to determine what configuration to apply to messages sent to that channel.
- Since MediaWiki 1.33, if no logger
@defaultis defined, it is defined with the handler@default; if there is no handler@defaultit is defined as a stream handler to php://stderr with minimum level ERROR (T196906). - Since MediaWiki 1.35.1, a logger configured as
[]orfalseis silenced (T196906). - Processors
- A processor adds or modifies contextual information of a log event.
- Including the
Monolog\Processor\PsrLogMessageProcessorhandler is recommended to make Monolog expand PSR-3{name}placeholders in the message body. - The MediaWiki provided
MediaWiki\Logger\Monolog\WikiProcessorprocessor will add'host' => wfHostname(),'wiki' => wfWikiID(),'mwversion' => $wgVersion,'reqId' => \WebRequest::getRequestId()and if running from CLI'cli_argv' => implode( ' ', $_SERVER['argv'] )to the log event.
- Including the
- Handlers
- Each logger should have one or more handlers attached to it.
Monolog\Handler\StreamHandlerwrites log events to a file or PHP stream.- MediaWiki's
MediaWiki\Logger\Monolog\LegacyHandlercan take the same file or UDP endpoint syntax as used by $wgDebugLogGroups.
- Formatters
- The formatters normalize and format incoming records for the handlers. If not specified in the config, a default formatter will be selected by the handler.
MediaWiki\Logger\Monolog\LegacyFormattermimics the legacy log message formatting ofwfDebug,wfDebugLog,wfLogDBErrorandwfErrorLogglobal functions by delegating the formatting toMediaWiki\Logger\LegacyLogger.
Usage
[edit]Minimal example
[edit]This configuration logs everything to a single file, /var/log/mediawiki/log.
The file should be writable by MediaWiki (e. g. sudo mkdir -p /var/log/mediawiki && sudo chown www-data /var/log/mediawiki).
Each log entry corresponds to a single line, and the structured data is appended to the message.
$wgMWLoggerDefaultSpi = [
'class' => '\\MediaWiki\\Logger\\MonologSpi',
'args' => [ [
'loggers' => [
'@default' => [
'processors' => [ 'wiki', 'psr' ],
'handlers' => [ 'stream' ]
],
],
'processors' => [
'wiki' => [ 'class' => '\\MediaWiki\\Logger\\Monolog\\WikiProcessor' ],
'psr' => [ 'class' => '\\Monolog\\Processor\\PsrLogMessageProcessor' ],
],
'handlers' => [
'stream' => [
'class' => '\\Monolog\\Handler\\StreamHandler',
'args' => [ '/var/log/mediawiki/log' ],
'formatter' => 'line'
],
],
'formatters' => [
'line' => [ 'class' => '\\Monolog\\Formatter\\LineFormatter' ],
]
] ]
];
Example from the MediaWiki\Logger\MonologSpi PHP doc comments
[edit]$wgMWLoggerDefaultSpi = array(
'class' => '\\MediaWiki\\Logger\\MonologSpi',
'args' => array( array(
'loggers' => array(
'@default' => array(
'processors' => array( 'wiki', 'psr', 'pid', 'uid', 'web' ),
'handlers' => array( 'stream' ),
),
'runJobs' => array(
'processors' => array( 'wiki', 'psr', 'pid' ),
'handlers' => array( 'stream' ),
)
),
'processors' => array(
'wiki' => array(
'class' => '\\MediaWiki\\Logger\\Monolog\\WikiProcessor',
),
'psr' => array(
'class' => '\\Monolog\\Processor\\PsrLogMessageProcessor',
),
'pid' => array(
'class' => '\\Monolog\\Processor\\ProcessIdProcessor',
),
'uid' => array(
'class' => '\\Monolog\\Processor\\UidProcessor',
),
'web' => array(
'class' => '\\Monolog\\Processor\\WebProcessor',
),
),
'handlers' => array(
'stream' => array(
'class' => '\\Monolog\\Handler\\StreamHandler',
'args' => array( 'path/to/your.log' ),
'formatter' => 'line',
),
),
'formatters' => array(
'line' => array(
'class' => '\\Monolog\\Formatter\\LineFormatter',
),
),
) ),
);
Example from MediaWiki-Vagrant's "elk" role
[edit]You can setup logging to an Elasticsearch, Logstash and Kibana (ELK) log aggregation stack in MediaWiki-Vagrant by enabling the elk role:
vagrant roles enable elk; vagrant provision
This role configures the wiki to log to local files and also to feed Logstash via an intermediate Redis queue.
$wgMWLoggerDefaultSpi = array(
'class' => '\\MediaWiki\\Logger\\MonologSpi',
'args' => array( array(
'loggers' => array(
'@default' => array(
'processors' => array( 'wiki', 'psr', 'pid', 'uid', 'web' ),
'handlers' => array( 'default', 'redis' ),
),
'wfDebug' => array(
'handlers' => array( 'default' ),
'processors' => array( 'psr' ),
),
'profileoutput' => array(
'handlers' => array( 'profiler' ),
'processors' => array( 'psr' ),
),
),
'processors' => array(
'wiki' => array(
'class' => '\\MediaWiki\\Logger\\Monolog\\WikiProcessor',
),
'psr' => array(
'class' => '\\Monolog\\Processor\\PsrLogMessageProcessor',
),
'pid' => array(
'class' => '\\Monolog\\Processor\\ProcessIdProcessor',
),
'uid' => array(
'class' => '\\Monolog\\Processor\\UidProcessor',
),
'web' => array(
'class' => '\\Monolog\\Processor\\WebProcessor',
),
),
'handlers' => array(
'default' => array(
'class' => '\\MediaWiki\\Logger\\Monolog\\LegacyHandler',
'args' => array( '/vagrant/logs/monolog-'.date('Ymd').'.log' ),
'formatter' => 'line',
),
'redis' => array(
'class' => '\\Monolog\\Handler\\RedisHandler',
'args' => array(
function() {
$redis = new Redis();
$redis->connect( '127.0.0.1', 6379 );
return $redis;
},
'logstash'
),
'formatter' => 'logstash',
),
'profiler' => array(
'class' => '\\MediaWiki\\Logger\\Monolog\\LegacyHandler',
'args' => array( '/vagrant/logs/profiler-'.date('Ymd').'.log' ),
'formatter' => 'profiler',
),
),
'formatters' => array(
'line' => array(
'class' => '\\Monolog\\Formatter\\LineFormatter',
),
'logstash' => array(
'class' => '\\Monolog\\Formatter\\LogstashFormatter',
'args' => array( 'mediawiki', php_uname( 'n' ), null, '', 1 ),
),
'profiler' => array(
'class' => '\\Monolog\\Formatter\\LineFormatter',
'args' => array( "%datetime% %message%\n\n", null, true, true ),
),
),
) ),
);