Manual:MonologSpi.php

MediaWiki file: MonologSpi.php
Location:	includes/debug/logger/ (includes/Debug/logger/ in 1.46 or later)
Source code:	master • 1.44.2 • 1.43.5 • 1.39.15
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 @default is defined, it is defined with the handler @default; if there is no handler @default it is defined as a stream handler to php://stderr with minimum level ERROR (T196906).

Since MediaWiki 1.35.1, a logger configured as [] or false is silenced (T196906).

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(), 'wiki' => wfWikiID(), 'mwversion' => $wgVersion, 'reqId' => \WebRequest::getRequestId() and if running from CLI 'cli_argv' => implode( ' ', $_SERVER['argv'] ) 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.

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', 'context' ],
 'handlers' => [ 'stream' ]
 ],
 ],
 'processors' => [
 'wiki' => [ 'class' => '\\MediaWiki\\Logger\\Monolog\\WikiProcessor' ],
 'psr' => [ 'class' => '\\Monolog\\Processor\\PsrLogMessageProcessor' ],
 'context' => [ 'class' => '\\MediaWiki\\Logger\\Monolog\\ContextProcessor' ],
 ],
 '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 ),
 ),
 ),
 ) ),
);

Retrieved from "https://www.mediawiki.org/w/index.php?title=Manual:MonologSpi.php&oldid=7958982"