Manuel:Journalisation structurées

From mediawiki.org
This page is a translated version of the page Manual:Structured logging and the translation is 100% complete.
Version de MediaWiki :
1.25

La journalisation structurée est l'enregistrement opérationnel (debogage) dans le journal, des données structurées pour faciliter le post traitement ultérieur. C'est différent de la Enregistrer dans Special:Log .

Depuis MediaWiki 1.25, la PSR-3 logging standard est disponible pour être utilisée par MediaWiki core et les extensions pour remplacer les appels de débogage wfDebug et wfDebugLog. La norme PSR-3 permet de joindre un tableau de données contextuelles à chaque message de journal pour fournir des paires clé-valeur structurées.

Conversion de wfDebug et wfDebugLog en PSR-3

Obtenir un journal à partir de LoggerFactory

use MediaWiki\Logger\LoggerFactory;

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

MyCoolLoggingChannel doit être le nom d'une extension (ou préfixé avec le nom) ou l'un des canaux de journalisation principaux.

Utiliser des niveaux de gravité informatifs

$logger->debug()
Ce sont des messages qui sont utiles pour le développement local et sont généralement trop "spammy" pour sortir sur un wiki de production. Cela inclurait généralement tout ce qui est actuellement enregistré via wfDebug.
$logger->info()
Informations de modification d'état précieuses. Ce niveau permet d'enregistrer des informations qui seraient utiles dans un environnement de production pour tracer le chemin d'une demande qui a finalement rencontré une erreur. Il s'agit actuellement du niveau automatiquement associé aux appels wfDebugLog lorsqu'il est mappé à PSR-3.
$logger->warning()
Condition d'erreur logicielle, telle qu'une erreur récupérable ou une autre condition qui ne doit généralement pas être vue mais qui ne s'interrompt pas pour l'opération en cours.
$logger->error()
Erreur matérielle, telle qu'une exception interceptée sans chemin de récupération.

La norme PSR-3 inclut d'autres niveaux de gravité, mais ils ne sont pas recommandés pour une utilisation dans MediaWiki.

Ajouter des données structurées au contexte de journalisation

Toutes les méthodes de journalisation prennent un objet de contexte facultatif, par exemple :

public function warning( $message, array $context = [] );

Vous devez ajouter des informations structurées utiles à vos messages de journalisation dans cet objet de contexte que d'autres peuvent utiliser pour rechercher les messages associés et suivre la cause de l'erreur. Ceci est particulièrement important et utile pour les messages de niveau avertissement et erreur où l'opérateur du wiki ne connaît peut-être pas le chemin du code et doit être capable de produire un bon rapport de bogue.

  • Si vous passez un objet Exception dans le paramètre de contexte, il DOIT être dans la clé 'exception' (par ex. 'exception' => $theExceptionCaught) [1]
  • Joindre des paramètres ou un autre état intéressant aux messages. Vous pouvez utiliser des objets ou tout autre type ; ils seront convertis en chaînes de manière raisonnable (par exemple en utilisant la méthode magique __toString si elle existe).
  • Les paramètres standard (nom du wiki, nom du serveur, etc.) seront ajoutés automatiquement. Les détails dépendent du service de journalisation que vous utilisez, mais vous utiliserez probablement MediaWiki\Logger\Monolog\WikiProcessor.
  • Remplacez les fausses structures telles que les éléments séparés par des tabulations, les paires étiquette=valeur/étiquette : valeur ou la sérialisation json.
  • Record stack traces by creating an exception object, adding it to the log context and then discarding it (e.g. 'exception' => new RuntimeException()).

De nombreux agrégateurs de journaux essaient de dédupliquer les journaux par message, alors essayez de garder les détails modifiables hors du message et de les déplacer dans le contexte. Le logger remplacera tous les jetons à l'intérieur des accolades par la valeur correspondante du contexte. Par exemple, le code

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

aboutira à quelque chose comme

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()
...

Pour une compatibilité maximale avec les différents backends de journalisation, n'utilisez pas ces clés dans vos données de contexte :

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

Configuration de votre wiki pour la journalisation structurée

Avertissement Avertissement : L'implémentation de la journalisation héritée par défaut dans MediaWiki "supprime" la plupart des informations de contexte !

Pour la compatibilité descendante, si vous utilisez la configuration par défaut de MediaWiki et avez configuré journalisation de base, que vous fournissiez un objet de contexte à ces méthodes de journalisation ou aux fonctions globales de MediaWiki telles que wfDebugLog( 'myChannel', $someMessage, 'private', $someContext ), les informations de l'objet de contexte n'apparaissent pas dans les fichiers journaux que vous avez configurés. Vous devez implémenter un meilleur enregistreur, tel que monolog, comme l'enregistreur "interface de fournisseur de services". Voir $wgMWLoggerDefaultSpi et Manual:MonologSpi .

Voir aussi