Requests for comment/Structured logging

Request for comment (RFC)

Structured logging
Component	General
Creation date	3 December 2013
Author(s)	Bryan Davis, Ori Livneh, Aaron Schulz
Document status	complete

This is a request for comment about adding Structured logging to MediaWiki. It specifies a data model for MediaWiki log messages and an interface for generating log messages that conform to the model.

By "data model" we simply mean an agreed-upon set of fields containing metadata that describes the context in which the log message was generated. The model specifies the name of each field and the value it can hold. Log messages generated via the interface that we propose below would conform to this model, allowing them to be serialized to a machine-readable format.A standard for machine-readable metadata common to all log messages would make it possible to query, collate, and summarize operational data in ways that are currently very difficult to achieve.

We think that the ability to cross-reference logs and query by context will make troubleshooting bugs easier. We also think that ongoing analysis of aggregated log data would reveal which files, interfaces, and code paths are especially prone to bugs or poor performance, and that this information would help us make MediaWiki more reliable and performant.

Problems with the current interface

Most operational logging in MediaWiki is done via wfDebugLog calls. Messages logged via wfDebugLog specify a topic name (or a log bucket). This name usually identifies the name of the component that is emitting the log message. Some parts of the code which generate different kinds of log messages have compound topic names that describe the type of log message being logged, usually in terms of severity ("memcached-serious", for example). The ad hoc overloading of the log group property to encode severity is a good example of existing usage that is twisting the interface to overcome its limitations. This is a good indication that the current interface is inadequate.

Because there is no established standard for encoding severity, the density of logging calls in MediaWiki code varies greatly. Access to the production logs is limited, and many developers will only ever review logs generated on their development instance and consequently fail to appreciate the cost of excessively verbose logging at scale. The instrumentation of code is often pitched to its initial development rather than its ongoing maintenance.

To keep chatty code from drowning out important log data, the logging setup on the Wikimedia production cluster does not automatically transmit all logging topics to the log processor. A developer must first manually enroll the log bucket by adding it to the $wgDebugLogGroups configuration var. The problem with this approach is that the absence of log data from a particular component is typically noticed when it is needed the most: that is, when the component is suspected of misbehaving in ways that are difficult to reproduce or reason about. Thus log buckets are usually enabled to help solve a particular bug, and they are commonly left enabled long after the motivation for enabling them has ceased to be relevant. The overall effect is that Wikimedia's logs are curated on the basis of historic interest rather than abiding relevance.

Design principles

Filtering logs by severity and grouping logs by attributes only works if log messages are uniform in structure and content.

What we would need:

• tools for wider audience
• aggregation
• de-duplication
• cross system correlation
• alerting
• reporting

This is not a wholly new idea. Let's look at what's out there and see if we can find a solution or at least borrow the best bits.

Current logging

wfDebug( $text, $logonly = false )

Logs developer provided free-form text + optional global prefix string

Possibly has time-elapsed since start of request and real memory usage inserted between prefix and message

Delegates to wfErrorLog()

wfDebugMem( $exact = false )

Uses wfDebug() to log "Memory usage: N (kilo)?bytes"

wfDebugLog( $logGroup, $text, $public = true)

Logs either to a custom log sink defined in $wgDebugLogGroups or via wfDebug()

Default

Prepends "[$logGroup] " to message

Custom sink

May log only a fraction of occurrences via mt_rand() sampling

Prepends wfTimestamp( TS_DB ) wfWikiID() wfHostname(): to message

Delegates to wfErrorLog() to actually write to sink

wfLogDBError( $text )

Enabled/disabled with $wgDBerrorLog sink location

Logs "$date\t$host\t$wiki\$text" via wfErrorLog() to $wgDBerrorLog sink

Date format is 'D M j G:i:s T Y' with possible custom timezone specified by $wgDBerrorLogTZ

wfErrorLog( $text, $file )

Writes $text to either a local file or a UDP packet depending on the value of $file

UDP

If $file ends with a string following the host name/IP it will be used as a prefix to $text

The final message with optional prefix added will be trimmed to 65507 bytes and a trailing newline may be added

FILE

$text will be appended to file unless the resulting file size would be >= 0x7fffffff bytes (~2G)

wfLogProfilingData()

Delegates to wfErrorLog() using $wgDebugLogFile sink

Creates a tab delimited log message including timestamp, elapsed request time, requesting IPs, and request URL followed by a newline and the profiler output.

Date is from gmdate( 'YmdHis' )

Recent changes logging

Transport and serialization format may be specified via $wgRCFeeds

Various implementations in includes/rcfeeds/, including IRC, UDP & Redis.

Proposal

Serialization Format

Rather than dive down a rabbit hole of trying to find a universal spec for log file formats let's just keep things simple. PHP loves dictionaries (well they call them arrays but whatever; key=value collections) and has a pretty fast json formatter. So the simplest thing that will work reasonably well would be to keep log events internally as PHP arrays and serialize them as json objects. This will be relatively easy to recreate on other internally developed applications as well with the possible exception of apps written in low level languages such as C that don't have ready made key=value data structures.

Data collected

Here's a list of the data points that we should definitely have:

timestamp

Local system time that event occurred either as UNIX epoch timestamp or ISO 8601 formatted string

date( 'c' )

host

FQDN of system where event occurred

php_uname( 'n' )

source

Name of application generating events; correlates to APP-NAME of RFC 5424

'Mediawiki'

pid

Unix process id, thread id, thread name or other process identifier

getmypid()

severity

Message severity (RFC 5424 levels)

'WARN'

channel

Log channel. Often the function/module/class creating message (similar to wgDebugLogGroups groups)

get_class( $this )

message

Message body

"Help! I'm trapped in a logger factory!"

Additionally we suggest adding a semi-structured "context" component to logs. This would be a collection of key=value pairs that the developers determine to be useful for debugging. There should be two different methods available to add such data. The first is as an optional argument to the logging method itself and the second is a global collection patterned after the Log4J Mapped Diagnostic Context (MDC).

The local collection is useful for obvious reasons such as attaching class/method state data to the log output and deferring stringification of resources in the event that runtime configuration is ignoring messages of the provided level.

file

Source file triggering message

line

Source line triggering message

errcode

Numeric or string identifier for the error

exception

Live exception object to be stringified by the log event emitter

args

key=value map of method arguments

The global collection is very useful for attaching global application state data to all log messages that may be emitted. Examples of data that could be included:

vhost

Apache vhost processing request

$_SERVER['HTTP_HOST']

ip

Requesting ip address

$_SERVER['REMOTE_ADDR']

user

Authenticated user identity

req

Request ID; UUID or similar token that can be used to correlate all log messages connected to a given request

API

The developer facing API is the PSR-3 logging interface standard with the possibility for MediaWIki specific extensions.

class MWLogger implements \Psr\Log\LoggerInterface {

    /**
     * Logs with an arbitrary level.
     *
     * @param string|int $level
     * @param string $message
     * @param array $context
     */
    public function log( $level, $message, array $context = array() );

    /**
     * System is unusable.
     *
     * @param string $message
     * @param array $context
     */
    public function emergency( $message, array $context = array() );

    /**
     * Action must be taken immediately.
     *
     * Example: Entire website down, database unavailable, etc. This should
     * trigger the SMS alerts and wake you up.
     *
     * @param string $message
     * @param array $context
     */
    public function alert( $message, array $context = array() );

    /**
     * Critical conditions.
     *
     * Example: Application component unavailable, unexpected exception.
     *
     * @param string $message
     * @param array $context
     */
    public function critical( $message, array $context = array( ) );

    /**
     * Runtime errors that do not require immediate action but should typically
     * be logged and monitored.
     *
     * @param string $message
     * @param array $context
     */
    public function error( $message, array $context = array( ) );

    /**
     * Exceptional occurrences that are not errors.
     *
     * Example: Use of deprecated APIs, poor use of an API, undesirable things
     * that are not necessarily wrong.
     *
     * @param string $message
     * @param array $context
     */
    public function warning( $message, array $context = array() );

    /**
     * Normal but significant events.
     *
     * @param string $message
     * @param array $context
     */
    public function notice( $message, array $context = array() );

    /**
     * Interesting events.
     *
     * Example: User logs in, SQL logs.
     *
     * @param string $message
     * @param array $context
     */
    public function info( $message, array $context = array() );

    /**
     * Detailed debug information.
     *
     * @param string $message
     * @param array $context
     */
    public function debug( $message, array $context = array() );

}

MWLogger also provides two static methods:

    /**
     * Get a named logger instance from the currently configured logger factory.
     *
     * @param string $channel Logger channel (name)
     * @return MWLogger
     */
    public static function getInstance( $channel );

    /**
     * Register a service provider to create new MWLogger instances.
     *
     * @param MWLoggerSpi $provider Provider to register
     */
    public static function registerProvider( MWLoggerSpi $provider );

The MWLogger::getInstance() method is the means by which most code would acquire an MWLogger instance. It will in turn delegate the creation of MWLoggers to a class implementing the MWLoggerSpi interface:

interface MWLoggerSpi {

    /**
     * Get a logger instance.
     *
     * @param string $channel Logging channel
     * @return MWLogger Logger instance
     */
    public function getLogger( $channel );

}

This service provider interface will allow the backend logging library to implemented in multiple ways. The $wgMWLoggerDefaultSpi global provides the class name of the default MWLoggerSpi implementation. This can be altered via the normal means. Alternately MWLogger::registerProvider() can be invoked early in the application setup to inject an alternate SPI implementation.

See Gerrit change 112699 for a full proof of concept implementation including a MWLoggerMonologSpi class that creates MWLogger instances backed by the monolog logging library. Additional SPI implementations may follow if desired by the community.

The proof of concept code also demonstrates the use of a $wgUseMWLoggerForLegacyFunctions feature flag that configures the legacy global logging methods to emit logging events via MWLogger.

Managing third-party libraries

The use of PSR-3 and monolog introduces the need to manage third-party code dependencies for MediaWiki core. Although there are some third-party components in includes/libs, to my knowledge this is the first large scale use of external PHP code by MediaWiki core.

In a more perfect world, MediaWiki would already be a system that assembled a collection of libraries using a well defined dependency management system. This has actually been envisioned in at least two RFCs (MediaWiki libraries and Third-party components).

The proof of concept implementation hews close to the approach proposed in MediaWiki_libraries with the addition of Composer as a dependency management system.

A new libs directory is used to isolate the Composer managed code from the rest of MediaWiki core. Within the libs directory a composer.json file defines the exact versions of external code to import:

{
  "name": "wikimedia/mediawiki-core"
  ,"require": {
    "php": ">=5.3.2"
    ,"psr/log": "1.0.0"
    ,"monolog/monolog": "1.7.0"
  }
  ,"preferred-install": "dist"
  ,"prefer-stable": true
  ,"config": {
    "vendor-dir": "."
  }
}

The vendor-dir is set to ".", meaning the directory that contains the composer.json file. composer install is run once to import the initial libraries, generate a composer.lock file recording the origin of those dependencies and create the autoload.php file that will be used to import the libraries. This entire collection of files is then committed as a patch to gerrit to become an integral part of the MediaWiki core repository along with a change to the includes/AutoLoader.php script to require the lib/autoload.php class autoloader script generated by Composer.

When new versions of the currently imported libraries are desired or additional libraries are needed for additional MediaWiki core components, Composer can be used to safely manage the change.

1. Edit composer.json to add/update library dependencies.
2. Run composer update inside the libs directory.
3. (Optionally) Remove tests, documentation, non-PHP 5.3 compatible files.
4. Add and commit changes as a gerrit patch.
5. Review and merge.

Since this composer.json file is not in the root of the MediaWiki core project, it should not conflict with the Extension management with Composer RFC.

Implementation

An original proof of concept implementation was submitted as Gerrit change 112699. The approach of using Composer to manage external dependencies was given a +1 by Tim. The monolithic patch was then split into four smaller patches for closer review and approval:

Gerrit change 119939 Add Composer managed libraries

Import Psr\Log and Monolog libraries to MW-Core in a new "libs" directory which is managed using Composer. The includes/AutoLoader.php script has been modified to require the lib/autoload.php class autoloader script generated by Composer.

Gerrit change 119940 Add a PSR-3 based logging interface

The MWLogger class is actually a thin wrapper around any PSR-3 LoggerInterface implementation. Named MWLogger instances can be obtained from the MWLogger::getInstance() static method. MWLogger expects a class implementing the MWLoggerSpi interface to act as a factory for new MWLogger instances. A concrete MWLoggerSpi implementation using the Monolog library is also provided.

Gerrit change 119941 Enable MWLogger logging for legacy logging methods

Introduces the $wgUseMWLoggerForLegacyFunctions that enables the use of the MWLogger PSR-3 logger for legacy global logging functions. When

enabled wfDebug, wfDebugLog and wfLogDBError will route their log messages to MWLogger instances.

Gerrit change 119942 Enable MWLogger logging for wfLogProfilingData

Output structured profiling report data from wfLogProfilingData when $wgUseMWLoggerForLegacyFunctions is enabled.

See Also

Relevant bugs

• bug 14601 [Use wfDebugLog instead of wfDebug by default]
• bug 49757 [Better monitoring and error reporting of Errors and Exceptions]

Related RFCs

• Third-party components
• MediaWiki libraries

RFC Review

• 2013-12-04
• 2013-03-19

Logging standards

• https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md
• http://www.graylog2.org/about/gelf
• https://wiki.mozilla.org/Services/Sagrada/Metlog
• http://cee.mitre.org/

Additional commentary on logging

• User:BDavis_(WMF)/Projects/Structured_logging
• http://gregoryszorc.com/blog/2012/12/06/thoughts-on-logging---part-1---structured-logging/
• https://journal.paul.querna.org/articles/2011/12/26/log-for-machines-in-json/
• http://carolina.mff.cuni.cz/~trmac/blog/2011/structured-logging/
• http://dev.splunk.com/view/logging-best-practices/SP-CAAADP6
• https://delicious.com/bd808/logging