Remontée d'exceptions

La remontée d'exceptions est le cœur du SDK. Une fois configuré, chaque exception que Laravel reporte est transmise à votre dashboard.

Capture automatique

Au démarrage, le SDK enregistre un callback reportable() additif sur le handler d'exceptions de l'application :

$handler->reportable(function (Throwable $e): void {
    app(Monitor::class)->report($e);
});

Comme le callback est additif, il ne remplace ni ne supprime votre logging existant ni les autres handlers reportable, il se contente d'en transmettre une copie à Quiet Guard. Toute exception qui atteint le handler (exceptions non capturées, ou tout ce que vous passez à report()) est capturée, à l'exception de celle levée en servant une requête qui correspond à ignore_paths : voir Configuration.

La capture est fail-safe : une panne réseau, une mauvaise configuration ou une erreur serveur dans le SDK est avalée et ne remonte jamais vers l'application hôte.

Remontée manuelle

Utilisez la façade Monitor pour reporter explicitement une exception gérée :

use QuietGuard\LaravelMonitor\Facades\Monitor;

try {
    $this->chargeCustomer($order);
} catch (\Throwable $e) {
    Monitor::report($e);

    // Relancez ou récupérez comme bon vous semble.
    throw $e;
}

Monitor::report() ne lève jamais d'exception. Il ne fait silencieusement rien lorsque la remontée est désactivée, lorsque l'URL/la clé du serveur est absente, ou lorsque l'environnement courant n'est pas dans la liste blanche.

Vous pouvez résoudre le même objet depuis le conteneur :

app(\QuietGuard\LaravelMonitor\Monitor::class)->report($e);

Ce qui est envoyé

Chaque rapport est posté sur l'endpoint /api/v1/ingest du serveur et contient :

L'exception

• classe, message, code, fichier et ligne ;
• la pile d'appels complète par défaut (MONITOR_TRACE_LIMIT=0): chaque frame, pour que les erreurs profondes gardent leur origine ; fixez un nombre de frames pour alléger les payloads. Chaque frame est réduit à file, line, function, class et type (les arguments ne sont jamais envoyés, ils peuvent contenir des secrets).

Le contexte

• environment, release (depuis MONITOR_RELEASE), php_version, laravel_version, occurred_at (ISO 8601) ;
• source : console en CLI/file, ou http pour les requêtes web.

Pour les requêtes HTTP, le contexte inclut en plus :

• url et method ;
• request : en-têtes, query string et corps: le password / password_confirmation du corps étant retirés et l'ensemble passé au masquage ;
• user : uniquement l'identifiant de l'utilisateur authentifié (id), jamais ses attributs.

Masquage

Avant que toute charge utile ne quitte l'application, les données de requête et de contexte sont masquées récursivement : toute clé dont le nom contient l'un des termes configurés (insensible à la casse) voit sa valeur remplacée par [scrubbed].

Les termes par défaut sont :

password, password_confirmation, passphrase, token, secret,
authorization, cookie, php_auth_pw, api_key, access_token,
referer, referrer, x-forwarded-for, x-real-ip, cf-connecting-ip,
true-client-ip, x-client-ip, forwarded

Pour ajouter les vôtres, publiez la config (php artisan vendor:publish --tag=monitor-config) et étendez le tableau scrub dans config/monitor.php :

'scrub' => [
    ...config('monitor.scrub'),
    // les vôtres :
    'credit_card',
    'iban',
],

Conservez chaque terme livré, sauf à vouloir l'enlever. Réécrire le tableau à la main, c'est ainsi que passphrase et les en-têtes d'IP visiteur disparaissent de la liste sans bruit.

La correspondance se fait par sous-chaîne : api_key masque donc aussi stripe_api_key, et token masque csrf_token.

Masquage par forme de la valeur

La liste scrub ci-dessus regarde le nom du champ. Elle ne voit pas une adresse écrite au milieu d'un message d'erreur, dans un segment d'URL, ou dans un champ que quelqu'un a appelé reference.

La liste redact regarde la valeur elle-même, sur votre serveur, avant tout envoi :

'redact' => ['email', 'iban', 'nir', 'card', 'phone'],

Les formes qui portent une clé de contrôle sont vérifiées et non simplement reconnues : une référence de commande à seize chiffres n'est pas prise pour un numéro de carte, et un IBAN doit passer le modulo 97. Chaque valeur masquée indique ce qui a été caché, par exemple Utilisateur [redacted:email] introuvable, de sorte que le message reste lisible.

Retirez les motifs qui produisent des faux positifs sur vos données, ou mettez 'redact' => [] pour tout désactiver. Pour vos propres formes :

'redact_custom' => ['customer_ref' => '/CUST-\d{6}/'],

Envoi en arrière-plan

Lorsque MONITOR_QUEUE est défini, les exceptions sont dispatchées comme job en file SendExceptionToMonitor (2 tentatives) au lieu d'être envoyées en ligne. Cela sort la remontée du chemin critique de la requête. Voir Configuration.

Regroupement côté serveur

Le SDK ne fait qu'envoyer les données ; le serveur regroupe les occurrences en incidents par empreinte, rouvre les régressions et corrèle les releases aux commits. Consultez la documentation du serveur pour la manière dont les incidents sont affichés et gérés.