Configuration

Le SDK se configure entièrement via des variables d'environnement, fusionnées dans l'espace de configuration monitor. Publier config/monitor.php est optionnel (voir Installation).

Configuration minimale

Ajoutez ce qui suit au .env de votre application :

MONITOR_ENABLED=true
MONITOR_KEY=votre-cle-api-projet

# Uniquement pour une instance auto-hébergée : le service hébergé est le défaut
MONITOR_URL=https://monitor.example.com

• MONITOR_KEY est la clé d'API par projet générée dans le dashboard Quiet Guard. Elle n'est affichée qu'une seule fois, à la création du projet. Consultez la documentation du serveur pour savoir comment créer les projets et les clés.
• MONITOR_URL vaut https://quietguard.dev par défaut, c'est-à-dire le service hébergé : sur le service hébergé, vous n'avez que la clé à coller. Renseignez-la pour pointer le SDK vers votre propre instance si vous auto-hébergez.

Une URL de base qui se termine déjà par /api ou /api/v1 est acceptée et normalisée : le SDK ajoute lui-même /api/v1/..., le suffixe est donc retiré plutôt que doublé. Les deux formes fonctionnent, si bien que lire l'adresse de l'API dans le dashboard ne peut plus répondre 404 en silence à chaque appel.

Lorsque MONITOR_KEY est vide, le SDK reste totalement silencieux, il n'envoie jamais rien et ne lève jamais d'erreur. La clé est la seule chose qui puisse manquer : à partir de la version 0.3.1, une MONITOR_URL vide n'arrête rien, elle vaut le service hébergé (jusqu'à la version 0.3.0, elle coupait en silence la remontée des exceptions et des logs). Une machine qui a une clé et pas d'adresse, une préproduction par exemple, remonte donc désormais au service hébergé. Pour la garder muette, videz sa clé ou utilisez MONITOR_ENABLED=false, qui le dit.

Toutes les options

Environnements

Par défaut, le SDK ne reporte que depuis production et staging. Autrement dit, en local rien n'est envoyé tant que vous ne modifiez pas la liste :

# Reporter depuis tous les environnements
MONITOR_ENVIRONMENTS=

# Ou ajouter local le temps de tester l'intégration
MONITOR_ENVIRONMENTS=production,staging,local

Le contrôle s'appuie sur app()->environment() de Laravel, c'est-à-dire la valeur de votre APP_ENV. Les battements automatiques passent en plus par leur propre liste, MONITOR_HEARTBEAT_ENVIRONMENTS, production par défaut : les deux listes doivent l'admettre.

Release

La release est l'identifiant de la version déployée, attaché à chaque événement : le serveur s'en sert pour rattacher une anomalie à un déploiement précis et, quand c'est un SHA de commit, pour ouvrir depuis l'anomalie le commit synchronisé qui tournait au moment de l'erreur.

Vous n'avez rien à renseigner dans le cas courant : quand MONITOR_RELEASE est vide, le SDK détecte la release tout seul, une fois par processus, en lisant dans l'ordre un fichier REVISION à la racine de l'application (Capistrano, Deployer et la plupart des scripts de déploiement en écrivent un), puis le .git/HEAD du checkout, en suivant la référence de branche jusqu'au commit. Une valeur explicite gagne toujours :

MONITOR_RELEASE=v2.4.1

Pour n'envoyer que la valeur configurée, par exemple quand le checkout présent sur le serveur n'est pas la branche qui tourne réellement, coupez la détection :

MONITOR_RELEASE_AUTO=false

Automatiser le hash git au déploiement

Le serveur ne relie une anomalie à un commit que si la release est le SHA de ce commit. Selon la façon dont vous déployez, voici comment ce hash arrive dans MONITOR_RELEASE sans que personne ne le tape.

Laravel Forge. En mode zéro interruption, chaque répertoire de release est un checkout git : .git/HEAD porte le SHA et il n'y a rien à faire, un clone --depth 1 compris. En mode classique, ajoutez une ligne au script de déploiement après le git pull :

git rev-parse HEAD > REVISION

Envoyer. Envoyer expose le SHA déployé sous la variable {{ sha }} ; écrivez-le dans un fichier REVISION par un hook de déploiement, avant l'activation de la release :

cd {{ release }} && echo "{{ sha }}" > REVISION

GitHub Actions, ou toute intégration continue. Le SHA du commit est dans GITHUB_SHA ; écrivez-le dans le fichier .env de l'artefact déployé, ou dans un fichier REVISION embarqué avec lui :

echo "MONITOR_RELEASE=${GITHUB_SHA}" >> .env

Si votre configuration est mise en cache, relancez php artisan config:cache après avoir modifié .env, sinon la valeur en cache reste l'ancienne.

Docker. Passez le hash à la construction de l'image et figez-le dans une variable d'environnement :

ARG GIT_SHA
ENV MONITOR_RELEASE=$GIT_SHA

docker build --build-arg GIT_SHA=$(git rev-parse HEAD) .

Un serveur mis à jour par git pull. Le .git/HEAD du dépôt est lu ; il n'y a rien à faire.

Le serveur compare la release au SHA complet de 40 caractères des commits synchronisés ; un SHA abrégé d'au moins 7 caractères est résolu comme un préfixe. Un tag (v2.4.1) fonctionne comme étiquette d'un déploiement mais ne renvoie vers aucun commit.

Envoi asynchrone

Par défaut, les rapports sont envoyés de façon synchrone pendant la requête, dans la limite de MONITOR_TIMEOUT. Pour sortir ce travail du cycle de vie de la requête, placez-le dans une file :

# Utiliser une connexion de file précise
MONITOR_QUEUE=redis

# Ou la connexion par défaut
MONITOR_QUEUE=true

Les rapports sont alors dispatchés comme jobs en file (SendExceptionToMonitor, SendLogsToMonitor) ; un worker de file doit donc tourner.

MONITOR_QUEUE désigne une connexion de file, c'est-à-dire une clé de votre tableau queue.connections, et non un nom de file. MONITOR_QUEUE=default, =monitoring ou =high ne désignent aucune connexion dans une application Laravel standard. Une telle valeur est refusée pour les remontées d'exceptions : le SDK écrit un avertissement nommant les connexions qui existent et envoie le rapport de façon synchrone, parce qu'un rapport qui bloque la requête vaut mieux qu'un rapport qui ne part jamais. Les lots de logs lisent le même réglage et n'ont pas ce repli : donnez-lui donc un nom que votre application déclare réellement.

Deux propriétés du chemin en file méritent d'être connues. Les payloads sont masqués avant d'être mis en file, si bien que les formes que le masquage par la valeur existe pour arrêter ne séjournent jamais en clair dans vos propres tables jobs et failed_jobs. Et un job dont l'envoi a échoué lève, si bien que la seconde de ses deux tentatives est réelle et qu'un échec définitif est enregistré dans failed_jobs au lieu d'être marqué comme réussi.

Chemins de requête ignorés

Par défaut, toute exception est reportée, où qu'elle survienne. Renseignez ignore_paths avec une liste de chemins de requête dont les exceptions ne sont jamais reportées, dans la syntaxe acceptée par le Illuminate\Http\Request::is() de Laravel :

'ignore_paths' => ['api/v1/*'],

Vide par défaut. Une commande console porte une requête factice dont le chemin est /, qui ne correspond à aucun de ces motifs : ignore_paths ne fait donc jamais taire un job en file ni une tâche planifiée, seulement les requêtes HTTP. Cela ne concerne que les exceptions, pas les logs.

Cette option existe pour une application qui héberge son propre endpoint de supervision : les exceptions levées en le servant ne doivent pas lui être reportées en retour.

Clés masquées

La liste monitor.scrub par défaut masque toute clé de requête/contexte dont le nom contient l'un de ces termes (insensible à la casse, récursif) :

password, password_confirmation, passphrase, token, signature, 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

referer et referrer portent l'adresse de la page d'où vient le visiteur, et une URL est l'endroit où les applications placent leurs secrets à usage unique : un lien de désinscription, un téléchargement signé, une réinitialisation de mot de passe, un lien de partage. Le masquage se fait par le nom, parce que cette valeur n'a aucune forme qu'un masqueur de valeurs saurait reconnaître.

Les six derniers sont les en-têtes qui portent l'adresse IP du visiteur. Derrière un reverse proxy, ce qui est la topologie de production ordinaire, l'un d'eux contient l'adresse de la personne qui a déclenché l'erreur. C'est une donnée personnelle, et elle ne vous concerne pas vous mais vos visiteurs, qui n'ont rien choisi. Elle est donc masquée par défaut. Si vous disposez d'une base légale pour la conserver, retirez la ligne correspondante : la décision vous appartient, en votre qualité de responsable de traitement.

Pour l'étendre, publiez la config et modifiez le tableau scrub. Les valeurs masquées sont remplacées par [scrubbed]. Voir Remontée d'exceptions pour les détails.