Choisir un signal
Commencez l’investigation d’un échec par les problèmes ou les logs. Utilisez
une trace disponible pour examiner une exécution. Utilisez la tendance d’une
métrique pour examiner une période plus large. Pour l’activité et la rétention,
lisez Analyses produit.
Capturez uniquement les champs dont une investigation a besoin. Utilisez des
noms de service, d’opération et de métrique stables. N’envoyez pas
d’identifiants, de données de paiement ni de corps de requête bruts. Le guide
Contrôler les données capturées présente les
contrôles disponibles.
Logs
Un log (ou journal) est un enregistrement émis par l’application à un instant précis. Un log utile contient :- L’heure source de l’événement.
- Une gravité canonique.
- Le périmètre du projet et du service.
- L’environnement et la version.
- Les identifiants de trace et de span quand le log a un contexte de trace actif.
- Quelques attributs courts et nommés qui donnent le contexte de l’événement.
occurred_at, severity,
project_id, service_name, environment, release, trace_id, span_id
et attributes. Placez le contexte dans des attributs nommés, pas dans le
texte du message.
Des logs de plusieurs services affichés dans une même vue n’ont pas de relation
de trace entre eux. Seul le contexte de trace crée cette relation.
Traces
Une trace contient les spans d’une requête ou d’une opération. Un span racine n’a pas de parent. Un span enfant identifie son parent. Tous les spans d’une trace ont le même ID de trace et des ID de span différents. Consultez Traçage distribué. Un log, un problème, une action ou une métrique envoyé sans contexte de trace actif reçoit une trace de capture. Cette trace contient uniquement des spans de capture. Elle ne montre pas le chemin d’une requête. Consultez Spans de capture.Métriques
Une métrique enregistre une valeur mesurée dans le temps. Lisez chaque métrique avec son nom, son unité, ses dimensions, son projet, sa période et son intervalle. LogBrew choisit lavalue de chaque point à partir du kind et de
la temporality de la métrique :
Par exemple, 3 échantillons d’un compteur delta avec les valeurs
2, 3 et
5 dans un même intervalle donnent un point avec une value de 10 et un
sample_count de 3. Avec 3 échantillons d’une jauge qui ont les mêmes
valeurs, dans cet ordre, le point a une value de 5. Une valeur p95 n’est pas
une moyenne. Environ 95 % des observations enregistrées sont inférieures ou
égales à cette valeur.
Avec status: "ready", l’agrégation dérivée est disponible. Avec
status: "limited", lisez aggregation.limitation et utilisez uniquement les
valeurs brutes. N’additionnez pas une jauge ni un flux cumulatif. Un intervalle
sans point n’est pas un zéro mesuré. Pour les champs de requête, lisez
Filtres de requête.
GET /api/telemetry/metrics/series renvoie ces points. Cette route exige project_id,
name et since. Chaque série a une seule identity avec un kind, une
unit et une temporality. Les séries dont l’identité diffère restent
séparées. Chaque point peut aussi contenir :
coverage.truncated vaut true quand series_limit a omis des séries de
plus faible volume. Pour comparer une période d’une métrique avec la période
précédente de même durée, exécutez :
Problèmes
Un problème regroupe des échecs répétés par empreinte stable. Il a une gravité, un statut, un nombre d’occurrences, une heure de première occurrence et une heure de dernière occurrence. Le détail d’un problème peut ajouter des chaînes d’exceptions, des frames de pile, des breadcrumbs, des logs associés et une relation de trace.last_seen_at correspond à l’occurrence la plus récente du groupe.
L’occurrence que vous sélectionnez peut être plus ancienne. Lisez les deux
heures.
Le status d’un problème vaut unresolved, resolved ou archived. La
version 1 des réponses de l’API affiche archived sous la forme ignored. Les
versions 2 et 3 ajoutent priority (high, medium ou low) et
priority_source. La version 3 ajoute aussi assignee. Consultez
Valeurs de statut et
Priorité.
Actions
Une action enregistre une activité produit. Une classification prise en charge la marque comme vue de page, vue d’écran ou interaction. Le nom de l’événement seul ne définit pas la classification. Utilisez Capture d’événements produit pour ajouter ce contexte. Une session n’est pas un utilisateur. Un sujet anonyme n’est pas un utilisateur identifié.Valeurs de gravité
LogBrew accepte les alias en entrée, en majuscules comme en minuscules. L’API,
la CLI et les événements en direct utilisent les valeurs canoniques. Les
valeurs de gravité inconnues sont rejetées. La gravité est l’urgence
enregistrée. Elle ne montre ni l’impact métier ni la cause racine.
Un utilisateur peut modifier la gravité affichée d’un problème ou d’un log. La
réponse contient alors un objet
triage avec effective_severity. Le champ
severity conserve la valeur capturée.
Lectures en direct et instantanées
logbrew read renvoie un instantané pour le projet, la période et les filtres
sélectionnés. Relancez la commande pour lire les nouveaux événements.
logbrew watch diffuse les nouveaux logs, problèmes et actions tant que la
connexion est ouverte. Cette commande ne diffuse ni les traces ni les
métriques. Un échec de connexion ne montre pas que le projet est vide.
États des preuves
Les réponses distinguent ces états : capturé, manquant, masqué, tronqué et indisponible. Les preuves de trace ont 4 états :available, not_linked,
not_found et unavailable. Consultez la
Vue d’ensemble pour leur
signification, et
Limites des preuves
pour les champs de couverture. Un SDK plus récent n’ajoute pas de champs aux
signaux qu’il a envoyés plus tôt.
Investiguer un projet
1
Trouver les problèmes non résolus
2
Lire un problème
Cette commande lit l’historique conservé du problème. Le filtre
--since
de la liste ne s’applique pas.3
Ouvrir une trace disponible
Utilisez l’ID de trace uniquement quand l’occurrence sélectionnée en
renvoie un.
4
Lire les preuves associées
Filtrez les logs, les actions et les métriques sur le même projet, le
même service, le même environnement et la même version. Ne reliez pas des signaux uniquement
par l’heure.