Aller au contenu

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 :

  1. Une ligne error report est écrite sur l’erreur standard, avec la pile (La ligne de journal).
  2. 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_errors sont notifiées des groupes nouveaux et récurrents (Groupes d’erreurs et notifications).
  3. 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.

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 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.fingerprint est identique pour chaque occurrence de la même erreur. Recherchez ou regroupez par ce champ.
  • my.error.where indique où cela s’est produit, par exemple client_api GET /api/v1/statuses/{id}.
  • request_id, job_id, trace_id et span_id permettent 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.
  • message est 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.

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 avec trace_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 message est 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 de my.error.fingerprint : chaque valeur d’une dimension est facturée comme une métrique à part. my.error.source et my.error.kind sont 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.

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.

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.

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).

  • Les personnes ayant manage_errors reçoivent la notification admin_error_group pour 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.created et error_group.regressed portent 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 exige manage_webhooks, et les événements exigent manage_errors.
  • Un groupe en sourdine ne notifie jamais.

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.

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 ».

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 429 ou 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).

Fenêtre de terminal
MY_ERRORS_EXPORTER=sentry
MY_ERRORS_SENTRY_DSN_FILE=/run/secrets/sentry_dsn # or MY_ERRORS_SENTRY_DSN; the DSN is a secret

Avec 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’étiquette service, 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 dans message ; associez-la à error.stack avec un pipeline de journaux, faute de quoi Datadog ne la voit pas comme une pile. L’exportateur sentry n’a besoin d’aucune association de ce genre.
Fenêtre de terminal
MY_ERRORS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 # or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
OTEL_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.

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

Mesure d’audience de ce site