Aller au contenu principal

Erreurs

Les erreurs sont déjà dans votre télémétrie — enfouies dans les évènements exception des spans, les spans en erreur et les logs ERROR/FATAL. Le module de suivi des erreurs les fait remonter en problèmes de premier plan : la même exception, vue 4 000 fois depuis le déploiement de 14h02, avec sa pile d'appels et un lien vers une trace qui l'a rencontrée.

Problèmes​

Un problème regroupe les occurrences qui partagent une empreinte — service + type d'exception + les premières frames normalisées de la pile (avec repli sur le message quand il n'y a pas de pile).

C'est la normalisation qui fait tenir le regroupement. Avant le hachage, avuru obs neutralise tout ce qui change à chaque occurrence : horodatages, UUID, identifiants hexadécimaux — identifiants de trace et de span notamment —, adresses mémoire, puis les suites de chiffres restantes, dont les numéros de ligne. L'empreinte reste donc stable entre les déploiements, et une erreur qui transporte l'identifiant de trace de sa propre requête dans son message forme toujours un seul problème, au lieu d'un problème par requête. Le titre du problème conserve la ligne brute, identifiants compris : il reste recherchable tel quel dans vos journaux.

Chaque problème porte :

  • Une pile d'appels — le site du plantage en haut, suivant les conventions sémantiques OTel exception.*.
  • Une chronologie des occurrences — première vue, dernière vue, nombre total, et un histogramme des occurrences sur la fenêtre.
  • Un lien vers la trace d'origine — pivotez de l'exception directement vers la requête qui l'a produite (et de là vers ses logs et ses spans).
  • Une source — selon que l'occurrence vient d'un évènement de span, d'un span en erreur, d'un log, ou d'un SDK Sentry.

Deux voies d'entrée​

Aucune des deux ne demande de modifier l'application.

  1. Dérivée, en base (par défaut). Des vues matérialisées ClickHouse transforment l'OTLP que vous envoyez déjà — évènements d'exception des spans, spans en erreur et logs ERROR/FATAL — en problèmes au moment de l'insertion. Zéro instrumentation : si un service atteint déjà avuru obs, ses exceptions se regroupent déjà en problèmes.
  2. Ingestion via SDK Sentry (optionnelle). Le gateway expose un récepteur au protocole Sentry sur :4319. Pointez n'importe quel SDK Sentry vers avuru obs en changeant son DSN — aucune réécriture, aucun nouvel agent. C'est le seul signal que l'eBPF ne peut pas atteindre : les erreurs JavaScript du navigateur. Voir l'intégration SDK Sentry.

Les évènements Sentry sont stockés sous forme d'enregistrements de log OTel : la même vue matérialisée des logs qui dérive les problèmes de vos logs ERROR en dérive aussi depuis les évènements Sentry — et ceux-ci apparaissent également dans l'explorateur de logs.

Lire la liste​

Au-dessus de la liste, un bandeau de statistiques dit ce que représente l'ensemble filtré, sur la même fenêtre et les mêmes filtres que les lignes qui le suivent :

  • Problèmes — combien correspondent en ce moment.
  • Nouveaux dans la fenêtre — parmi eux, combien ont été vus pour la première fois dans la fenêtre, et non simplement revus. C'est le chiffre qui attrape un déploiement raté.
  • Régressés — combien avaient été résolus et ont enregistré une occurrence depuis.
  • Événements — le total des occurrences produites dans la fenêtre, avec un histogramme montrant quand elles ont eu lieu.
  • Services principaux — les services les plus bruyants. Cliquez sur l'un d'eux pour y filtrer la liste ; recliquez pour retirer le filtre.

Le bandeau et la liste lisent le même ensemble via la même requête : ils ne peuvent donc pas se contredire. Résolvez un problème, il quitte les deux d'un coup ; une récurrence le ramène dans les deux, signalé comme régression.

La liste charge jusqu'à 200 problèmes et défile sur place, les onglets, les filtres et le bandeau restant fixes au-dessus. Si un filtre en trouve plus de 200, la liste le dit et nomme le total réel — affinez par service, statut ou recherche pour voir le reste.

Cycle de triage​

Chaque problème a un statut :

  • Non résolu — la valeur par défaut ; quelque chose à examiner.
  • Résolu — corrigé ; sort de la liste active.
  • Ignoré — connu et mis en sourdine ; ne réapparaîtra pas.

La détection de régression est calculée à la lecture : un problème résolu qui enregistre une occurrence après sa résolution est signalé comme une régression — le bug que vous aviez clos la semaine dernière est de retour.

Cas d'usage​

  • Attraper un mauvais déploiement. Une seule empreinte nouvelle dont la première occurrence coïncide avec le rollout de 14h02, c'est la réponse — pas de spéléologie dans les logs. Le guide Attraper un mauvais déploiement le déroule de bout en bout sur le bac à sable fourni.
  • Les erreurs navigateur sans nouvel outillage. Votre frontend utilise déjà un SDK Sentry ? Changez son DSN et les exceptions navigateur atterrissent à côté des traces backend qui les ont causées. Voir l'intégration SDK Sentry.
  • Veille de régression. Résolvez un problème et oubliez-le — si le bug repart en production, le problème se signale lui-même comme régression au lieu de se noyer dans un nouveau ticket.
  • Trier des services jamais instrumentés. Les problèmes dérivent de la télémétrie que l'eBPF et l'OTLP livrent déjà : même les services sans SDK obtiennent des erreurs regroupées et triables.

Configuration​

  • modules.errorTracking.enabled — activé par défaut. La dérivation apporte de la valeur gratuitement à partir de données que vous envoyez déjà, elle est donc active d'emblée. Désactivez-la et les tables, l'API /errors et l'entrée de menu disparaissent toutes.
  • gateway.sentry.enabled — désactivé par défaut. Le port d'ingestion Sentry ouvre une surface réseau (:4319), il est donc opt-in. Il nécessite aussi le module logs (modules.logs.enabled), car les évènements Sentry sont stockés comme enregistrements de log. Les clients navigateur ont en plus besoin que :4319 soit exposé et que le CORS soit configuré pour leurs origines.
  • AVURUOBS_RETENTION_ERRORS_DAYS — durée de conservation des occurrences, 30 jours par défaut.

Limites de la v1​

  • Une erreur peut apparaître en double. Une même erreur logique à la fois journalisée et enregistrée comme évènement d'exception de span produit deux problèmes — sources différentes, empreintes différentes. La déduplication par corrélation de trace à la lecture reste à venir.
  • Pas de rattrapage. La dérivation s'applique aux insertions après la migration ; les erreurs antérieures à l'activation du module ne sont pas reconstituées.
  • Liens de trace orphelins. Les erreurs sont conservées plus longtemps que les traces par défaut : un ancien problème peut donc pointer vers une trace déjà expirée — l'interface affiche alors un état « trace expirée ».

:::note Cette page s'étoffe Les alertes sur les problèmes nouveaux ou en hausse, l'upload de source maps (frames JS désobfusquées) et les clés DSN par projet sont sur la feuille de route. Voir la Feuille de route et l'État des fonctionnalités. :::