Open main menu

Manual:MonologSpi.php

(Redirected from Manual: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.

Contents

RequirementsEdit

MediaWiki\Logger\MonologSpi requires Monolog to be installed and available to your wiki. One way to do this is with Composer, by adding the following to your composer.local.json and running composer update --no-dev.

{
    "require": {
        "monolog/monolog": "1.23.0"
    }
}

DetailsEdit

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 = array(
    'class' => '\\MediaWiki\\Logger\\MonologSpi',
    'args' => array( array(
        'loggers' => array(
            '@default' => array ( /* Template for any log channel without explicit config */ ),
            'some-special-log-channel' => array( /*...*/ ),
        ),
        'processors' => array( /*...*/ ),
        'handlers' => array( /*...*/ ),
        'formatters' => array( /*...*/ ),
    ) ),
);
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.
Processors
A processor adds or modifies contextual information of a log event.
  • Including the Monolog\Processor\PsrLogMessageProcessor handler is recommended to make Monolog expand PSR-3 {name} placeholders in the message body.
  • The MediaWiki provided MediaWiki\Logger\Monolog\WikiProcessor processor will add 'host' => wfHostname() and 'wiki' => wfWikiID() to the log event.
Handlers
Each logger should have one or more handlers attached to it.
  • Monolog\Handler\StreamHandler writes log events to a file or PHP stream.
  • MediaWiki's MediaWiki\Logger\Monolog\LegacyHandler can 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\LegacyFormatter mimics the legacy log message formatting of wfDebug, wfDebugLog, wfLogDBError and wfErrorLog global functions by delegating the formatting to MediaWiki\Logger\LegacyLogger.

UsageEdit

Minimal exampleEdit

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 as JSON.

$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 commentsEdit

$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',
           ),
           'redis' => array(
               'class'     => '\\Monolog\\Handler\\RedisHandler',
               'args'      => array(
                   function() {
                       $redis = new Redis();
                       $redis->connect( '127.0.0.1', 6379 );
                       return $redis;
                   },
                   'logstash'
               ),
               'formatter' => 'logstash',
           ),
           'udp2log' => array(
               'class' => '\\MediaWiki\\Logger\\Monolog\\LegacyHandler',
               'args' => array(
                   'udp://127.0.0.1:8420/mediawiki'
               ),
               'formatter' => 'line',
           ),
       ),
       'formatters' => array(
           'line' => array(
               'class' => '\\Monolog\\Formatter\\LineFormatter',
            ),
            'logstash' => array(
                'class' => '\\Monolog\\Formatter\\LogstashFormatter',
                'args'  => array( 'mediawiki', php_uname( 'n' ), null, '', 1 ),
            ),
       ),
    ) ),
);

Example from MediaWiki-Vagrant's "elk" roleEdit

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