Cette page est une traduction automatique de la page en anglais, qui fait foi. Lire la page en anglais
Signalement d’erreurs
Comment le serveur vous informe de ses propres bogues et défaillances, où lire les rapports sur chaque plateforme, et comment les envoyer à un outil de suivi d’erreurs. Les métriques vous disent que quelque chose ne va pas ; un rapport d’erreur vous dit ce qui a échoué, avec sa pile. La référence de la configuration liste tous les paramètres.
Trois choses arrivent à chaque rapport, quelle que soit votre configuration :
- Une ligne
error reportest écrite sur l’erreur standard, avec la pile (La ligne de journal). - Le rapport est compté dans un groupe d’erreurs dans la base de données. L’écran d’administration affiche les groupes, et les personnes ayant la permission
manage_errorssont notifiées des groupes nouveaux et récurrents (Groupes d’erreurs et notifications). - Si vous définissez
errors_exporter, le rapport part aussi vers un service externe (Envoyer les rapports à un service).
Rien ne quitte le serveur tant que vous ne définissez pas errors_exporter.
Ce qui est signalé
Section intitulée « Ce qui est signalé »| Signalé | Non signalé (les métriques et les autres lignes de journal le couvrent) |
|---|---|
| Une panique dans un gestionnaire HTTP, une tâche ou une tâche de fond | Les réponses 4xx (entrée invalide, autorisation, limites de débit) et le mode maintenance |
| Une erreur derrière une réponse 5xx de l’API client, de l’API d’administration, des pages de connexion, d’ActivityPub, d’OAuth ou des médias | Une requête dont le client est parti |
Une tâche qui a définitivement échoué (dead) |
Une nouvelle tentative de tâche. Elle est signalée quand elle n’a plus de tentatives |
| Un échec au démarrage : une configuration invalide, ou une base de données ou un adaptateur qui ne peut pas être mis en place | Un contrôle de disponibilité échoué |
| Une erreur que le client web n’a pas gérée, envoyée au serveur par le navigateur | Les échecs causés par d’autres serveurs : nouvelles tentatives et abandons de livraison, signatures rejetées, récupérations distantes échouées |
| Le bruit propre au navigateur : un réseau perdu, les erreurs des extensions du navigateur et les chunks qu’un nouveau déploiement a supprimés |
La défaillance d’un service extérieur (e-mail, stockage, paiements, voix) n’est signalée que si elle fait échouer définitivement une tâche ou répondre une requête en 5xx. Une défaillance temporaire apparaît plutôt dans les métriques my.adapter.* (Exécuter le serveur).
Une panique dans une tâche de fond arrête le processus après avoir été signalée, de sorte que le serveur ne continue jamais à tourner dans un état défaillant. Votre plateforme le redémarre.
La ligne de journal
Section intitulée « La ligne de journal »La ligne a msg = error report et level ERROR (severity vaut CRITICAL lorsque l’échec arrête le processus).
Ses champs, et ce que fait le nettoyage sur eux, sont décrits dans Exécuter le serveur. En bref :
my.error.fingerprintest identique pour chaque occurrence de la même erreur. Recherchez ou regroupez par ce champ.my.error.whereindique où cela s’est produit, par exempleclient_api GET /api/v1/statuses/{id}.request_id,job_id,trace_idetspan_idpermettent de retrouver les autres lignes de la même requête ou de la même tâche.- La ligne d’une erreur de requête contient
context.httpRequest: la méthode, la route sous forme d’URL (/api/v1/statuses/{id}, jamais le chemin demandé par le client) et le statut répondu. Error Reporting les affiche sur le groupe et peut filtrer par ces valeurs. messageest en dernier sur la ligne : le type et le message de l’erreur, un saut de ligne, puis la pile Go.- La pile commence là d’où l’erreur provient, pas là où elle a été signalée : pour une erreur de base de données, la fonction du serveur qui a exécuté la requête. Les erreurs de lieux différents tombent donc dans des groupes différents, aussi bien dans Error Reporting que dans l’écran d’administration.
Aucune autre ligne ne porte de pile.
Google Cloud (Cloud Run)
Section intitulée « Google Cloud (Cloud Run) »Cloud Error Reporting lit la ligne sans aucune configuration et liste les erreurs dans la console sous Error Reporting. Il est gratuit ; vous ne payez que Cloud Logging.
- Il regroupe les erreurs par type et par premiers cadres de la pile. Il ne peut pas utiliser l’empreinte du serveur ; un groupe dans Error Reporting peut donc différer d’un groupe dans l’écran d’administration.
- Il conserve les groupes pendant 30 jours, et vous notifie des nouvelles erreurs et des erreurs résolues qui se reproduisent, au plus 20 notifications par heure pour le projet. Configurez son canal de notification dans la console Google Cloud.
- Pour trouver ce qui s’est passé autour d’un signalement, cherchez dans Cloud Logging
jsonPayload."request_id"="<id>", ou la même chose avectrace_id.
Avec le module OpenTofu mycroblog-gcp, la section observability envoie les signalements ici par défaut (errors = "error-reporting") : elle active l’API Error Reporting et laisse errors_exporter à none.
CloudWatch Logs lit la ligne comme du JSON simple.
- Activez la détection d’anomalies de journaux pour le groupe de journaux. Elle signale un motif de ligne jamais vu auparavant et peut déclencher une alarme vers SNS. Elle ne lit que les 1 500 premiers caractères d’une ligne, ce pourquoi
messageest le dernier champ. Elle ne conserve pas d’état « résolu ». - Pour compter les signalements, créez un filtre de métrique tel que
{ $.msg = "error report" }. N’utilisez aucune dimension tirée demy.error.fingerprint: chaque valeur d’une dimension est facturée comme une métrique à part.my.error.sourceetmy.error.kindsont sans risque. - Trouvez le contexte avec Logs Insights :
filter `request_id` = "<id>".
Avec le module OpenTofu mycroblog-aws, la section observability conserve les signalements dans CloudWatch Logs par défaut (errors = "cloudwatch"), avec errors_exporter à none. La détection d’anomalies de journaux reste une étape qui vous incombe.
Auto-hébergé
Section intitulée « Auto-hébergé »Lisez la ligne dans le journal du conteneur : docker compose logs my | jq -c 'select(.msg == "error report")'.
Avec metrics_exporter = prometheus, l’alerte MyErrorReportsIncreasing (Alertes et runbook) prévient quand les rapports augmentent fortement ; le compteur qui la sous-tend est my.errors.reported.
Pour des notifications qui n’exigent aucun service extérieur, utilisez l’écran d’administration et les webhooks ci-dessous. Pour un outil de suivi, utilisez errors_exporter.
Groupes d’erreurs et notifications
Section intitulée « Groupes d’erreurs et notifications »Le serveur compte les rapports par empreinte dans la base de données. Cela n’exige aucun paramètre ni service supplémentaire, et écrit peu : le premier rapport d’une empreinte est écrit immédiatement, et les suivants sont additionnés en mémoire et écrits une fois par minute. Un arrêt brutal du processus peut perdre les compteurs de la dernière minute ; les lignes de journal ne sont pas perdues ainsi. Les compteurs de plus de 90 jours sont supprimés chaque jour. Si c’est la base de données qui a échoué, le rapport reste uniquement dans la ligne de journal.
L’écran d’administration
Section intitulée « L’écran d’administration »Les personnes dont le rôle a manage_errors (le rôle intégré admin l’a) voient « Erreurs » dans le menu d’administration (/admin/errors).
- La liste affiche les groupes, les ouverts par défaut, les plus récemment vus d’abord. Filtrez par état (ouvert, résolu, en sourdine, tous les états) et par source (le serveur, le client web). Chaque ligne affiche la première ligne du message, où il s’est produit, les nombres des dernières 24 heures et des 7 derniers jours, la date de la dernière occurrence et son état.
- La page d’un groupe commence par ce que vous pouvez faire dans son état (« Résoudre » et « Mettre en sourdine » pour un groupe ouvert, « Mettre en sourdine » pour un groupe résolu, « Réactiver » pour un groupe en sourdine). Elle affiche les faits du groupe (où, le message, la première et la dernière date et version, l’empreinte), ses nombres des dernières 24 heures et des 7 derniers jours, la dernière occurrence (date, version, rôle du processus, les types, l’ID de requête et l’ID de trace, et la pile), les occurrences par heure sur les 90 derniers jours, les plus récentes d’abord, et l’historique de ses changements d’état. L’empreinte, l’ID de requête, l’ID de trace et la pile ont un bouton de copie : collez les ID dans votre recherche de journaux.
- « Résoudre » sert pour une erreur que vous avez corrigée. Si elle se reproduit sur une autre version du serveur, le groupe se rouvre et notifie de nouveau. La même erreur sur la version qui a été résolue est seulement comptée, de sorte que les dernières requêtes de l’ancienne version ne le rouvrent pas.
- « Mettre en sourdine » continue de compter mais n’envoie aucune notification ni aucun événement de webhook. « Réactiver » rouvre le groupe.
Les mêmes actions sont disponibles sous la forme GET /api/v1/admin/error_groups et POST /api/v1/admin/error_groups/{id}/resolve (/mute, /unmute).
Notifications et webhooks
Section intitulée « Notifications et webhooks »- Les personnes ayant
manage_errorsreçoivent la notificationadmin_error_grouppour un nouveau groupe d’erreurs et pour une récurrence. Au plus 10 arrivent par heure pour l’ensemble du serveur ; le reste de l’heure est regroupé en une seule notification indiquant que d’autres erreurs ont été signalées. Elles peuvent aussi la recevoir par e-mail (Modération). - Les événements de webhook
error_group.createdeterror_group.regressedportent les mêmes groupes : vous pouvez donc les envoyer à Slack, à Discord ou à un outil d’automatisation (Webhooks du serveur, Référence des webhooks). Le webhook exigemanage_webhooks, et les événements exigentmanage_errors. - Un groupe en sourdine ne notifie jamais.
Erreurs du client web
Section intitulée « Erreurs du client web »Le client web envoie les erreurs que ses écrans n’ont pas gérées à POST /api/v1/client_errors sur votre propre serveur : aucun tiers ne les voit et aucun paramètre de sécurité du contenu ne change. Le serveur répond 204 à tout et abandonne ce qu’il n’accepte pas : un corps de plus de 16 KiB, une pile sans fichier de votre propre client web, et plus de 10 rapports par minute depuis une même adresse IP. La même erreur est envoyée une fois par affichage de page, et au plus 20 par affichage de page.
Un rapport envoyé sans session connectée est compté et journalisé mais ne notifie personne à lui seul, de sorte qu’un script anonyme ne peut pas remplir votre boîte de réception. Le groupe notifie quand le navigateur d’une personne connectée le signale aussi.
Les piles sont celles du build minifié et ne sont pas retraduites vers les sources : lisez donc d’abord la route et le message. La version est celle du serveur qui a servi la page. Une page ouverte hors ligne, ou après 3 secondes sans réponse, provient de la copie du navigateur, qui indique la version du moment où le navigateur a stocké le client web : une version plus ancienne avec le même client web.
Mesures d’expérience utilisateur
Section intitulée « Mesures d’expérience utilisateur »Le client web envoie des échantillons de sa rapidité de réponse à POST /api/v1/client_measurements sur votre propre serveur, de la même façon que ses erreurs : le temps qu’un écran met à apparaître (LCP) et à répondre à un appui (INP) sur chaque route, ses images longues, chaque navigation par type, chaque action par son ID (post.reply), ainsi que le temps d’aller-retour, la gigue et la perte de paquets des appels vocaux. Un échantillon ne nomme que la route, le type, l’action ou le transport de l’appel ; il ne porte aucun compte, aucune adresse ni aucune URL. Le serveur répond 204 à tout et accepte au plus 10 requêtes par minute d’une même adresse IP.
Le serveur compte les échantillons par heure dans la base de données, en écrivant une fois par minute, et les supprime après 30 jours. GET /api/v1/admin/ux_measurements (manage_errors) additionne les dernières 24 heures, ou hours jusqu’à 720, avec le 75e centile de chaque nom ; les métriques my.ux.duration et my.ux.call.packet_loss exportent les mêmes échantillons (Métriques). Chaque type conserve ses 200 premiers noms dans un processus ; les suivants sont comptés comme other.
La fonction est désactivée par défaut ; le paramètre d’instance ux_measurement l’active, et tant qu’elle est désactivée le serveur ne prend aucun échantillon (Paramètres de l’instance). Lorsqu’elle est activée, seule une part des sessions de navigateur envoie des échantillons, 10 % sauf si ux_measurement_share en définit une autre, chaque session étant tirée une fois au démarrage du client web.
Les personnes dont le rôle a manage_errors voient « Mesures d’expérience utilisateur » dans le menu d’administration (/admin/ux-measurements). Choisissez les dernières 24 heures, 7 jours ou 30 jours ; chaque métrique qui a des échantillons a un tableau de ses noms avec leurs échantillons et le 75e centile et, pour LCP et INP, la part des échantillons bons et mauvais (dans les 2,5 s et au-delà de 4 s pour LCP, dans les 200 ms et au-delà de 500 ms pour INP), un 75e centile au-delà du seuil de « bon » étant signalé. « Mesurer le client web », sous les tableaux, est le paramètre ux_measurement, que seules les personnes dont le rôle a aussi manage_settings modifient à cet endroit, avec son propre « Enregistrer ».
Envoyer les rapports à un service
Section intitulée « Envoyer les rapports à un service »Définissez errors_exporter pour envoyer aussi chaque rapport à un outil de suivi d’erreurs. La ligne de journal et les groupes dans la base de données restent actifs. Un rapport est envoyé une fois et jamais renvoyé, et rien n’attend le service.
| Valeur | Envoie vers |
|---|---|
none (par défaut) |
Nulle part |
sentry |
Tout service compatible Sentry à errors_sentry_dsn |
otlp |
Un collecteur ou un backend OpenTelemetry, sous forme d’enregistrements de journal |
errors_environment (par défaut production) nomme le déploiement sur chaque rapport, par exemple staging.
Les deux exporteurs envoient les mêmes champs nettoyés que la ligne de journal, avec l’empreinte et les ID de trace et de span, et rien sur l’hôte : ni nom d’hôte, ni adresse IP, ni utilisateur, ni corps de requête, ni en-tête, ni cookie.
Le serveur limite ce qu’il envoie pour que le service ne soit pas inondé :
- La même empreinte part au plus une fois par minute et par processus, et l’ensemble des rapports au plus 60 par minute. Le reste demeure dans le journal et dans les groupes.
- Jusqu’à 1 000 rapports attendent d’être envoyés. Un rapport qui trouve la file pleine est abandonné. À l’arrêt du serveur, celui-ci attend jusqu’à 2 secondes que la file se vide.
- Quand le service répond
429ou demande de ralentir (Retry-After,X-Sentry-Rate-Limits), le serveur cesse d’envoyer pendant cette durée. - Le serveur ne suit jamais une redirection du service, afin que la clé du DSN et le rapport n’aillent nulle part ailleurs : une redirection compte comme
failed. Utilisez le DSN que le service affiche, qui pointe lui-même vers son point d’entrée.
Surveillez le compteur my.errors.exported : my.outcome vaut success, dropped (au-delà d’une limite, la file était pleine, ou le service a demandé de ralentir) ou failed (le service était injoignable ou a refusé le rapport) (Exécuter le serveur).
Sentry, GlitchTip et Datadog
Section intitulée « Sentry, GlitchTip et Datadog »MY_ERRORS_EXPORTER=sentryMY_ERRORS_SENTRY_DSN_FILE=/run/secrets/sentry_dsn # or MY_ERRORS_SENTRY_DSN; the DSN is a secretAvec les modules OpenTofu, laissez les erreurs de la section observability aux paramètres, et le module crée pour vous le secret du DSN à remplir, que sa sortie secrets_to_fill liste :
observability = { errors = "settings" } settings = { errors_exporter = "sentry" } secrets = ["errors_sentry_dsn"]Le serveur parle lui-même le protocole Sentry ; aucun SDK Sentry n’intervient et aucune variable d’environnement SENTRY_* n’est lue. Il définit l’empreinte, afin que le service regroupe selon elle, et les étiquettes service (my), my.role, my.error.where et error.fingerprint. La version publiée est la version du serveur et l’environnement est errors_environment.
- Sentry (hébergé ou auto-hébergé) : copiez le DSN depuis les clés client du projet.
- GlitchTip : copiez le DSN du projet. Il est open source et fonctionne sur un petit serveur. Vérifiez quelles règles d’alerte votre version propose pour les problèmes nouveaux et récurrents.
- Datadog Error Tracking : utilisez le DSN Sentry de votre site Datadog,
https://<DD_API_KEY>@sentry-intake.<DD_SITE>/1. Datadog exige l’étiquetteservice, que le serveur définit toujours. Datadog stocke ces événements comme des journaux et les regroupe dans Error Tracking. Si vous envoyez plutôt la ligne de journal à Datadog avec un agent ou un redirecteur (Error Tracking for Logs), la pile se trouve dansmessage; associez-la àerror.stackavec un pipeline de journaux, faute de quoi Datadog ne la voit pas comme une pile. L’exportateursentryn’a besoin d’aucune association de ce genre.
Backends OTLP
Section intitulée « Backends OTLP »MY_ERRORS_EXPORTER=otlpOTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 # or OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20...Chaque rapport est un enregistrement de journal OpenTelemetry nommé exception, avec la sévérité ERROR (FATAL quand il arrête le processus), exception.type, exception.message, exception.stacktrace, my.error.fingerprint, my.error.where, my.error.source, my.error.kind, ainsi que les ID de trace et de span. Il circule via OTLP/HTTP (protobuf, gzip) avec la même ressource que les métriques et les traces.
Que le backend transforme ces enregistrements en erreurs groupées dépend du backend : certains construisent leurs vues d’erreurs à partir des seules données de trace, et Datadog a besoin de error.stack. Pour Sentry, GlitchTip et Datadog, utilisez sentry. Utilisez otlp quand vous voulez les enregistrements à côté de vos autres journaux.
Ce que le nettoyage garantit et ne garantit pas
Section intitulée « Ce que le nettoyage garantit et ne garantit pas »Le nettoyage s’exécute une fois, à la création du rapport : la ligne de journal, la base de données et chaque exporteur ne reçoivent donc que le texte nettoyé.
- Dans le message, les URL, les adresses e-mail, les identifiants
@user@host, les adresses IP, les UUID et ULID, et les nombres de 10 chiffres ou plus sont remplacés par<url>,<email>,<acct>,<ip>,<id>et<n>, et le message est tronqué à 1 KiB. - Dans la pile, les valeurs des arguments de fonction sont remplacées par
(...)et la pile est tronquée à 16 KiB. Les positions de fichier restent, relatives à l’arborescence des sources, de sorte que les chemins de la machine de build n’apparaissent pas. - Aucun rapport ne contient de corps de requête, d’en-tête, de query, de cookie, d’ID de compte, de nom d’utilisateur, d’adresse IP ni de User-Agent.
Le nettoyage repose sur des motifs : il ne garantit donc pas qu’un message ne contienne aucune donnée personnelle. Un nom, un texte libre ou un nombre de moins de 10 chiffres que cite un message d’erreur peut subsister. Le champ error des lignes ordinaires http request et job n’est pas nettoyé de cette façon. Considérez les journaux et l’outil de suivi d’erreurs comme des lieux susceptibles de contenir des fragments de contenu d’utilisateurs, et appliquez-leur le même contrôle d’accès et la même rétention qu’au reste de vos journaux. Dès que vous définissez errors_exporter, les règles de localisation, de rétention et d’accès de ce service s’appliquent aux rapports.
Pour les LLM et les agents de programmation :llms.txt,llms-full.txt, llms-small.txt