O registro estruturado é um registro (logging) operacional (de depuração) que inclui dados estruturados para facilitar o pós-processamento. It is distinct from Manual:Registrando na Special:Log which is logging for the benefit of wiki editors; structured logging is for the benefit of developers.

A partir do MediaWiki 1.25, o padrão de registro PSR-3 está disponível para uso pelo núcleo e pelas extensões do MediaWiki para substituir as chamadas de registro de depuração desatualizadas wfDebug e wfDebugLog. O padrão PSR-3 permite anexar um arranjo de dados de contexto a cada mensagem de registro para fornecer pares chave-valor estruturados.

Obter um registro a partir do LoggerFactory

use MediaWiki\Logger\LoggerFactory;

$logger = LoggerFactory::getInstance( 'MyCoolLoggingChannel' );

The parameter passed to LoggerFactory::getInstance (here MyCoolLoggingChannel) is the log channel name. How the channel name is used depends on the logging configuration (see below) but typically separate log channels can be directed to separate files or such. You should use something unique (typically the name of your extension) as the channel name to make it easier to separate unrelated log entries.

$logger->debug( 'Entered ' . __METHOD__ )

Essas mensagens são úteis para o desenvolvimento local e, em geral, são muito “spam” para serem exibidas em uma wiki de produção. Isso normalmente incluiria qualquer coisa que esteja sendo registrada atualmente via wfDebug.

$logger->info( 'Restoring page' )

Informações valiosas sobre mudanças de estado. Esse nível é um ótimo lugar para registrar informações que seriam úteis em um ambiente de produção ao rastrear o caminho de uma requisição que acabou apresentando um erro. Atualmente, esse é o nível automaticamente associado a chamadas wfDebugLog quando mapeadas ao PSR-3.

$logger->warning( 'Page is protected' )

Uma condição de erro “suave”, como um erro recuperável ou outra condição que normalmente não deveria ocorrer, mas que não está interrompendo a operação em andamento.

$logger->error( 'Page not found' )

Um erro grave, como uma exceção capturada sem caminho de recuperação.

O padrão PSR-3 inclui outros níveis de gravidade, mas eles não são recomendados para uso no MediaWiki.

Adicionar dados estruturados ao contexto de registro

Todos os métodos de registro recebem um arranjo de contexto opcional, por exemplo:

$logger->warning( 'page not found', [ 'user' => $user->getName(), 'title' => $page->getPrefixedText() ] );

Adicione informações estruturadas úteis às suas mensagens de registro nesse objeto de contexto para que outras pessoas possam usar para encontrar mensagens relacionadas ou registros de banco de dados relevantes e rastrear a causa do erro. Isso é especialmente importante e útil para mensagens do tipo warning e error em que o operador da wiki pode não estar familiarizado com o caminho do código e precisa ser capaz de registrar um bom relatório de bug.

• Se for passado um objeto Exception no parâmetro de contexto, ele DEVE estar na chave exception (p. ex.: $logger->error( 'got exception', [ 'exception' => $e ] )).
  • You can also generate an exception object on the fly, which is a good way of attaching a stack trace e.g. when logging an error in a utility function that's invoked in many places: $logger->warning( 'called with a user which does not exist', [ 'user' => $user->getName(), 'exception' => new RuntimeException() ] )
• Anexe parâmetros ou outros estados interessantes às mensagens. It's best to make sure the items in the context array are strings. (Other types might be allowed, depending on the logging service the wiki uses, but the behavior for non-string values is often unintuitive.) Many MediaWiki core classes have a __toString method which generates some debugging-friendly description of the object so you can just use things like (string)$titleValue.
  • If you do pass non-string values, try to use reasonably unique field names. This is mainly needed for Wikimedia production which sends the context data to Logstash, which requires all context data using same key to be of the same type (globally, across all log channels).
• Os parâmetros padrão (nome da wiki, nome do servidor, etc.) serão adicionados automaticamente. Os detalhes dependem do serviço de registro sendo usado, mas que na maioria dos casos é o MediaWiki\Logger\Monolog\WikiProcessor.
• Substitua pseudo-estruturas, como itens separados por tabulação, pares rótulo=valor ou rótulo:valor, ou JSON serializado.

Muitos agregadores de registros (log aggregators) tentam deduplicar os registros por mensagem; portanto, tente manter os detalhes mutáveis fora da mensagem e movê-los para o contexto. O registrador substituirá todos os tokens dentro de chaves pelo valor correspondente do contexto. Por exemplo, o código

$logger->error( 'Caught exception while trying to create user {user}: {exception}', [
    'user' => $user->getName(),
    'exception' => $e,
] );

resultará em algo como

Caught exception while trying to create user Foo: exception DatabaseException with message 'Unique constraint violation' in /srv/mediawiki/includes/Database.php:123
#0 /srv/mediawiki/includes/Database.php(456): Database::query()
...

Para obter compatibilidade máxima com vários backends de registro, não use essas chaves nos seus dados de contexto:

• message
• channel
• host
• level
• type
• @timestamp
• @version

Throw exceptions which implement INormalizedException (or, if you don't need a custom exception class, use NormalizedException) so that related exception messages can be grouped together in the logs.

You can convert Status and StatusValue objects into PSR-3 logging with:

$statusFormatter = MediaWikiServices::getInstance()->getFormatterFactory()->getStatusFormatter( RequestContext::getMain() );
[ $message, $context ] = $statusFormatter->getPsr3MessageAndContext( $status );
$logger->error( $message, $context );

Configurar uma wiki para produzir registros estruturados

Atenção:

A implementação padrão (e legada) de registro no MediaWiki elimina a maioria das informações de contexto!

Para compatibilidade com versões anteriores, caso estiver usando a configuração padrão do MediaWiki e tiver configurado o registro básico, ao fornecer um objeto de contexto para esses métodos de registro ou para as funções globais do MediaWiki, como wfDebugLog( 'myChannel', $someMessage, 'private', $someContext ), as informações no objeto de contexto não aparecerão nos arquivos de registro configurados. You should implement a better logger, such as monolog, as the logger "service provider interface". See $wgMWLoggerDefaultSpi and Manual:MonologSpi .

• Requests for comment/Structured logging
• PSR-3 logging standard
• Manual:Como depurar
• wikitech:logstash - Wikimedia feeds most of its MediaWiki logs into logstash, which understands the structured logging