Logs vers STDERR

Présentation

Ce plugin modifie le comportement standard de SPIP en matière de journalisation.

Par défaut, SPIP écrit ses journaux dans des fichiers situés dans le répertoire tmp/log/. Ce fonctionnement est adapté à des hébergements classiques, mais il devient moins pratique dans des environnements conteneurisés ou industrialisés, où les journaux sont généralement collectés depuis les flux système.

Dans ces contextes, il est souvent préférable d’envoyer les journaux applicatifs vers stdout et stderr, afin qu’ils soient pris en charge par l’infrastructure : Docker, Kubernetes, chaînes CI/CD, outils de supervision, centralisation des journaux, etc.

Ce plugin redirige donc les appels à spip_log() vers les flux système au lieu d’écrire dans tmp/log/.

Les journaux d’information sont envoyés vers stdout, tandis que les avertissements et erreurs sont envoyés vers stderr.

Objectif

Ce plugin permet de :

• adapter SPIP aux environnements conteneurisés ;
• éviter l’écriture de fichiers de journaux dans tmp/log/ ;
• centraliser les journaux avec les outils de l’infrastructure ;
• séparer les journaux d’information des avertissements et erreurs ;
• produire des lignes de journaux plus faciles à lire et à filtrer ;
• conserver les informations utiles de SPIP : niveau de gravité, contexte public ou privé, canal, PID, et informations de debug si elles sont activées.

Installation

1. Installer le plugin dans le répertoire plugins/.
2. Activer le plugin depuis l’espace privé de SPIP.

Aucune configuration supplémentaire n’est nécessaire côté SPIP pour un usage standard.

Configuration requise

Le plugin écrit par défaut dans les flux PHP suivants :

php://stdout
php://stderr

Ces flux doivent être correctement récupérés par l’environnement d’exécution.

Dans un environnement Docker, les journaux pourront généralement être consultés avec :

docker logs <conteneur>

Utilisation

Une fois le plugin activé, les appels habituels à spip_log() continuent de fonctionner :

spip_log('Mon message', 'mon_canal');

La différence est que les journaux ne sont plus écrits dans tmp/log/.

Le plugin s’appuie sur les niveaux ajoutés par spip_log() dans le message :

• HS:
• ALERTE:
• CRITIQUE:
• ERREUR:
• WARNING:
• !INFO:
• info:
• debug:

Ces préfixes sont convertis en niveaux normalisés, puis retirés du message final.

Les niveaux suivants sont envoyés vers stderr :

• hs
• alert
• critical
• error
• warning

Les niveaux suivants sont envoyés vers stdout :

• important
• info
• debug

Si aucun niveau SPIP n’est détecté dans le message, le niveau info est utilisé par défaut.

Format des journaux

Le plugin produit un format de ligne structuré sous cette forme :

[spip][niveau][contexte][canal][pid:xxx] message

Si la constante _LOG_STDERR_SITE est activée, le site est ajouté entre le contexte et le canal :

[spip][niveau][contexte][site][canal][pid:xxx] message

Si la constante _LOG_FILELINE est activée, le fichier, la ligne et la fonction d’origine sont ajoutés :

[spip][niveau][contexte][canal][pid:xxx][fichier:Lligne:fonction()] message

ou :

[spip][niveau][contexte][site][canal][pid:xxx][fichier:Lligne:fonction()] message

Les valeurs possibles pour le contexte sont :

• pri pour l’espace privé ;
• pub pour l’espace public.

Exemples

Un appel comme :

spip_log('Connexion MySQL opérationnelle', 'mysql');

produira une ligne proche de :

[spip][info][pri][mysql][pid:123] Connexion MySQL opérationnelle

Avec _LOG_STDERR_SITE activé :

[spip][info][pri][monsite][mysql][pid:123] Connexion MySQL opérationnelle

Un avertissement comme :

spip_log('Requête lente détectée', 'mysql', _LOG_AVERTISSEMENT);

sera envoyé vers stderr et produira une ligne proche de :

[spip][warning][pri][mysql][pid:123] Requête lente détectée

Une erreur comme :

spip_log('Connexion impossible à la base', 'mysql', _LOG_ERREUR);

sera également envoyée vers stderr :

[spip][error][pri][mysql][pid:123] Connexion impossible à la base

Configuration avancée

Par défaut, les flux utilisés sont :

define('_LOG_STDOUT_STREAM', 'php://stdout');
define('_LOG_STDERR_STREAM', 'php://stderr');

Il est possible de les surcharger dans config/mes_options.php si l’environnement d’hébergement nécessite d’autres chemins.

Exemple :

define('_LOG_STDOUT_STREAM', '/proc/self/fd/1');
define('_LOG_STDERR_STREAM', '/proc/self/fd/2');

Cette configuration peut être utile dans certains environnements Linux ou conteneurisés.

Identifier un site dans les journaux

Par défaut, le plugin n’ajoute pas d’information de site dans les journaux.

Dans un environnement mutualisé ou multi-sites, il est possible d’ajouter un identifiant de site dans les lignes de logs :

define('_LOG_STDERR_SITE', true);

Le plugin tentera alors automatiquement d’utiliser :

• _DIR_SITE si disponible ;
• sinon HTTP_HOST ;
• sinon default.

Il est également possible de définir explicitement un identifiant :

define('_LOG_STDERR_SITE', 'monsite');

Limitations

Avec ce plugin :

• les journaux ne sont plus écrits dans tmp/log/ ;
• les outils SPIP de consultation des fichiers de logs ne peuvent plus lire ces journaux ;
• la rotation des journaux n’est plus gérée par SPIP ;
• la conservation, la rotation et l’analyse des journaux doivent être prises en charge par l’infrastructure.

Cas d’usage

Ce plugin est particulièrement utile dans les environnements suivants :

• Docker ;
• Kubernetes ;
• chaînes CI/CD ;
• plateformes avec centralisation des journaux ;
• hébergements où les fichiers de journaux applicatifs ne doivent pas être conservés dans l’arborescence du site ;
• mutualisations SPIP ou infrastructures multi-sites.

Remarques

Ce plugin modifie volontairement un comportement historique de SPIP. Il est recommandé de l’utiliser lorsque l’environnement d’hébergement est conçu pour collecter les journaux depuis stdout et stderr.

Licence

GNU/GPL