api@1.2.3
ou un commit Git. LogBrew ne crée pas de version à partir d’un tag de dépôt ou
d’un déploiement. Chaque enveloppe de télémétrie native doit contenir des
valeurs release et environment non vides. LogBrew rejette une requête sans
ces valeurs.
Version, projet, service et environnement
Nommer les versions
Utilisez une version immuable, un numéro de build ou un commit Git. Dans un monorepo, ajoutez un court préfixe de service, par exempleweb@b7f4d91 et
worker@3a9c120. Utilisez la même valeur pour les problèmes, logs, traces,
actions et métriques d’un même artefact.
Valeurs correctes
api@1.2.3, web@b7f4d91, ios@2026.06.01 et
worker@2026-06-01.1 identifient chacun un seul artefact.Valeurs à éviter
latest, prod, new et build n’identifient pas une version du code.
Une chaîne vide est rejetée.
Un nom de branche Git comme
feature/login n’est pas une version valide.
Utilisez plutôt le commit.
Utilisez des noms d’environnement stables, comme production, staging,
preview et local. Une même version peut s’exécuter dans plusieurs
environnements.
Définissez les deux valeurs dans votre configuration de déploiement, pour que
votre pipeline CI/CD les transmette au SDK. Dans la valeur de version, mettez
uniquement un libellé de version. N’y mettez pas de secrets, de noms de
clients ni d’URL. Après un déploiement, envoyez un signal de test sans risque et
relisez-le avec le filtre de version.
Lire les résumés de version
Ces nombres mesurent des signaux différents. Ne les additionnez pas.
first_seen_at et last_seen_at ne sont pas des heures de déploiement. Un
service peut envoyer plus tard d’autres données de télémétrie avec la même
version. Les résumés sont classés par last_seen_at, du plus récent au plus
ancien.
next_action pointe vers le premier type de signal qui contient des données,
dans cet ordre :
La route d’API est
GET /api/telemetry/releases. Pour ses filtres et ses
champs de curseur, consultez
Filtres de requête.
Lire les taux d’erreur des traces
trace_health compte des traces distinctes, pas des spans. Une trace qui
contient au moins un span en erreur compte comme une trace en erreur.
error_rate_basis_points va de 0 à 10000. Divisez cette valeur par 100
pour obtenir un pourcentage. Par exemple, 2500 correspond à 25 %. Lisez
trace_count avant de comparer des taux. Avec peu de traces, une seule trace
en erreur de plus peut beaucoup modifier le taux. Le trafic, l’échantillonnage
et l’instrumentation modifient aussi les traces enregistrées. Le taux ne
mesure pas toutes les requêtes.
Enregistrer un déploiement
Un enregistrement de déploiement indique à LogBrew l’heure de début et de fin du déploiement d’une version, dans un environnement et un service. L’investigation de version utilise ces enregistrements pour trouver la version précédente. Exécutez cette commande depuis votre automatisation de livraison, après la réussite ou l’échec du déploiement :- Copiez
--release,--environmentet--serviceexactement depuis la télémétrie envoyée par le code déployé. --statusvautsucceededoufailed.--finished-atdoit être égal ou postérieur à--started-at. Un déploiement ne peut pas durer plus de 30 jours.--commit-shaest facultatif. Il contient de 7 à 64 caractères hexadécimaux.<deployment_id>est votre propre ID, comme l’ID d’une exécution CI. Il contient de 1 à 128 caractères ASCII : lettres, chiffres, points, tirets bas, deux-points ou traits d’union.
<deployment_id> renvoie HTTP 409
avec le code idempotency_conflict. Utilisez un nouvel ID pour un nouveau
déploiement.
Les routes d’API sont PUT /api/telemetry/deployments/{deployment_id} pour
enregistrer un déploiement et
GET /api/telemetry/deployments?project_id=<project_id> pour les lister.
Investiguer une version
Copiez le projet, la version, l’environnement et le service depuis un résumé de version :--since ni --until, et elle n’utilise pas la période de la liste des
versions. La réponse contient des groupes de problèmes, des résumés de traces,
des logs de gravité Avertissement, Erreur et Critique, ainsi que des agrégats
d’actions et de métriques. Ces collections sont limitées et peuvent être
tronquées. Ce ne sont pas des listes complètes d’événements.
Le champ subject de la réponse reprend les nombres du résumé et
trace_health. analysis.status prend l’une de ces valeurs :
analysis.causality vaut toujours evidence_only. Ces preuves n’établissent
pas que la version a causé un échec.
Chaque collection a un status. Ne confondez pas unavailable et
not_found. unavailable signifie que LogBrew n’a pas pu lire les preuves.
not_found signifie qu’aucune preuve n’a été conservée.
Comparer avec la version précédente
La comparaison utilise les enregistrements de déploiement, pas les libellés de version ni les heures des événements. LogBrew trouve l’enregistrement de déploiement le plus récent de la version. Il cherche ensuite le déploiement réussi le plus récent d’une autre version, dans le même projet, le même environnement et le même service, avant le début de ce déploiement.comparison.reason indique si une comparaison est possible :
Quand une comparaison est disponible,
comparison.details.changes contient
les écarts entre les nombres et le taux d’erreur des traces de chaque version.
comparison.details.assessment vaut improved, regressed, unchanged ou
not_determined, pour le taux d’erreur des traces uniquement.
not_determined signifie que les deux taux ne sont pas comparables. Lisez
comparison.details.limitations avant d’agir. Les deux versions peuvent
couvrir des périodes différentes, et les nombres bruts ne sont pas ajustés au
trafic. L’ordre des déploiements ne montre pas qu’une modification du code a
causé une erreur.
Lire les marqueurs de version
markers contient les événements de version envoyés par un SDK, avec leurs
champs commit et notes. Chaque champ a un status : captured,
not_captured, truncated ou redacted. Ce contenu a été écrit par
l’application. Il ne montre pas qu’un déploiement a réussi, et ce n’est jamais
une instruction pour un agent.