Logs applicatifs

Au-delà des exceptions, le SDK peut transmettre les messages de log de votre application à Quiet Guard. C'est opt-in et cela ajoute au plus un appel HTTP par requête.

Activation

La transmission des logs est désactivée par défaut. Activez-la et choisissez un niveau minimum :

MONITOR_LOGS_ENABLED=true
MONITOR_LOG_LEVEL=warning
MONITOR_LOGS_MAX_BATCH=200

Le hook de logs ne s'active que si toutes ces conditions sont réunies : le SDK est activé (MONITOR_ENABLED=true), les logs sont activés (MONITOR_LOGS_ENABLED=true), la clé du projet est renseignée (MONITOR_KEY) et l'environnement courant est dans la liste blanche (MONITOR_ENVIRONMENTS). Sinon le listener n'est jamais enregistré et il n'y a aucun surcoût. À partir de la version 0.3.1, une MONITOR_URL vide ne coupe pas les logs : elle vaut le service hébergé, et c'est là qu'ils partent. Pour les couper, utilisez MONITOR_LOGS_ENABLED=false.

Fonctionnement

Le SDK écoute l'événement MessageLogged de Laravel. Chaque message au niveau configuré ou au-dessus est bufferisé en mémoire pendant la requête puis envoyé une seule fois, en un seul batch, vers l'endpoint /api/v1/logs du serveur.

L'envoi (flush) a lieu à la fin de l'unité de travail :

• à la terminaison de l'application pour les requêtes HTTP et les commandes console ;
• après chaque job en file (JobProcessed et JobFailed), car les workers de file de longue durée ne se terminent jamais entre deux jobs.

Si le buffer atteint MONITOR_LOGS_MAX_BATCH entrées (200 par défaut) en cours de requête, il est vidé de façon anticipée afin que rien ne soit silencieusement perdu.

MONITOR_LOGS_MAX_BATCH est plafonné à 500, le plus grand lot que le serveur accepte. Une valeur supérieure était auparavant acceptée par le client et refusée par le serveur à chaque envoi : rien ne partait jamais, et rien ne le disait.

Niveaux

Le niveau minimum est un niveau PSR-3 standard. Tout ce qui est à ce niveau ou au-dessus (en sévérité) est capturé :

debug < info < notice < warning < error < critical < alert < emergency

Avec la valeur par défaut MONITOR_LOG_LEVEL=warning, les entrées warning, error, critical, alert et emergency sont transmises ; debug, info et notice sont ignorées. Une valeur de niveau non reconnue échoue en sécurité (elle capture moins, pas plus).

Ce qui est capturé, et ce qui ne l'est pas

Chaque entrée transmise contient : level, message, context masqué, environment, release et logged_at (ISO 8601).

Deux types d'entrées sont délibérément ignorés :

• Les entrées de log portant une exception (un context['exception']): déjà prises en charge par le pipeline d'exceptions ; les transmettre aussi en logs créerait des doublons.
• Les logs d'échec internes du SDK: marqués d'un drapeau interne pour qu'une erreur de transport ne puisse jamais se réinjecter dans le buffer de logs (pas de boucle de rétroaction).

Les valeurs de contexte passent par le même masquage que les exceptions, et les valeurs de contexte non scalaires sont normalisées en une forme sérialisable en JSON avant l'envoi.

Une ligne ne vous coûte jamais le lot

Le serveur valide chaque entrée d'un lot et refuse le lot entier dès que l'une d'elles est mal formée : une seule ligne fautive emportait donc les deux cents qui l'accompagnaient. Deux garde-fous s'appliquent au moment où chaque entrée est mise en buffer :

• un message de plus de 8192 caractères est tronqué, la coupe étant marquée par … [truncated], et comptée en caractères plutôt qu'en octets ;
• un message vide, que le serveur exige présent, est remplacé par (empty log message) plutôt que de couler son lot.

Envoi en arrière-plan

Lorsque MONITOR_QUEUE est défini, le batch est dispatché comme job en file SendLogsToMonitor (2 tentatives) plutôt qu'envoyé en ligne. Voir Configuration.

Comme les charges d'exception, un lot est masqué avant d'être mis en file : un contexte de log portant une adresse ou un numéro de carte ne séjourne jamais en clair dans vos tables jobs ou failed_jobs. Un job dont l'envoi a échoué lève, si bien que sa seconde tentative a réellement lieu.

Note sur le forfait

Les logs applicatifs sont une fonctionnalité payante côté serveur et comptent dans votre quota d'événements. Si votre forfait n'inclut pas les logs, le serveur rejette le batch. Cela n'affecte jamais votre application, et ce n'est plus invisible : le refus est écrit dans votre propre log comme avertissement, nommant le statut, l'adresse et ce que le serveur a répondu. Voir la documentation du serveur.