Annotations de la chronologie Orbit

Les annotations vous permettent d'ajouter du contexte à la chronologie d'un projet : l'incident qui s'est produit à 2h du matin, la version qui a modifié le flux de paiement, le flag de feature que quelqu'un a activé. Six mois plus tard, c'est la différence entre un graphique avec une étape mystérieuse et un graphique que vous pouvez expliquer.

Où se trouvent les annotations

Ouvrez Orbit, cliquez sur le projet, puis choisissez Timeline dans le groupe Observability de la barre d'onglets du projet. La page s'intitule Timeline annotations et se décrit comme marquant les incidents, les versions, les jalons et les notes sur votre chronologie de déploiement.

Les cinq types

Flag flip mérite son propre type pour une raison spécifique. Un changement de flag modifie le comportement en production sans générer de déploiement, ce qui ne laisse aucune trace dans l'historique des déploiements. Quand les performances changent un jour sans déploiement, un flag flip est très souvent la réponse, et seule une annotation vous le dira.

Créer une annotation

1. Cliquez sur New annotation.
2. Choisissez le Kind.
3. Définissez Occurred at. Par défaut, c'est maintenant, et vous pouvez antidater.
4. Écrivez un Title, jusqu'à 200 caractères.
5. Optionnellement, écrivez un Body, jusqu'à 4000 caractères, pour des notes, des liens ou du texte de postmortem.
6. Cliquez sur Create.

L'antidatage est important. Écrivez l'annotation quand vous avez le temps, et définissez l'heure à laquelle le fait s'est réellement produit, pour qu'elle se place au bon endroit sur la chronologie.

Filtrage

La barre de filtrage en haut propose All plus chaque type. Le filtrage sur Incident vous donne un historique des incidents pour le projet en une seule vue, ce que vous voulez exactement quand vous écrivez un bilan trimestriel ou que vous essayez de déterminer si un problème récurrent l'est vraiment.

Ancrer à un déploiement

Une annotation peut être attachée à un déploiement spécifique plutôt que de rester isolée. C'est comme cela que vous liez une conséquence à une cause : l'annotation voyage avec le déploiement qui l'a causée.

Utilisez-le pour le modèle classique d'un déploiement qui semblait correct et qui a causé un problème une heure plus tard. Ancrez l'incident à ce déploiement et la connexion est enregistrée de façon permanente, plutôt que de vivre dans la mémoire de quelqu'un.

Les incidents sont publiés

Les annotations d'incident sont la source de la section incidents de votre page de statut publique, si vous en avez une activée avec Show recent incidents activé.

Rédiger une bonne annotation d'incident

Pendant l'incident, soyez bref et factuel :

• Ce qui est affecté, dans les termes qu'un client utiliserait.
• Ce que vous savez, pas ce que vous soupçonnez.
• Quand vous ferez la prochaine mise à jour.

Après, ajoutez un corps avec la résolution : quelle était la cause, ce qui l'a résolu, et ce qui l'empêchera de se reproduire. Cela transforme l'annotation en un enregistrement permanent au lieu d'un instantané d'une mauvaise heure.

Résistez à l'envie d'adoucir. « Checkout était indisponible pendant 40 minutes » vieillit mieux que « certains clients ont peut-être connu des problèmes intermittents », tant comme déclaration publique que dans vos propres archives.

Supprimer

Chaque annotation a un contrôle de suppression. La confirmation dit simplement que cela ne peut pas être annulé.

Supprimez les fautes de frappe et les doublons. Ne supprimez pas les incidents parce qu'ils sont gênants : la valeur de la chronologie est qu'elle est complète, et un historique avec les mauvais jours supprimés ne peut rien vous dire sur les modèles.

Lire la chronologie par rapport à vos graphiques

Les annotations deviennent utiles quand vous les mettez à côté d'une métrique :

• Un changement d'étape dans les Web Vitals. Vérifiez la chronologie pour une version ou un flag flip le même jour : voir Orbit Web Vitals.
• Un saut dans la durée de construction. Cherchez un jalon tel qu'une mise à niveau de dépendance ou une restructuration de monorepo : voir Orbit Build Insights.
• Un ensemble de déploiements échoués. Une annotation d'incident l'explique généralement, et s'il n'y en a pas une, c'est en soi intéressant à savoir.

Créer des annotations automatiquement

Les annotations peuvent être créées via l'API Orbit, ce qui signifie que vos propres outils peuvent les écrire. Deux modèles valent la peine d'être configurés :

• Votre système d'alerte ouvre une annotation Incident quand il avertit quelqu'un, pour que la chronologie soit peuplée sans que personne ait besoin de se souvenir de le faire.
• Votre outil de feature flag écrit une annotation Flag flip à chaque changement, ce qui est le seul moyen fiable de conserver ce dossier.

Voir Orbit API Tokens and the REST API pour l'authentification et la référence d'endpoint.

Habitudes à développer

Une annotation par événement, mise à jour dans le corps. Pas cinq annotations suivant le même incident. La chronologie devrait être lisible d'un coup d'œil.

Annotez aussi les victoires banales. « Déplacé les images vers l'edge » à côté de la semaine où votre bande passante a baissé, c'est comme ça que vous prouvez que le travail en valait la peine.

Écrivez-le le même jour. Une annotation écrite une semaine plus tard est plus vague et généralement inexacte sur l'heure.

Dépannage

L'annotation n'est pas sur la page de statut. Son type n'est pas Incident, ou le commutateur Show recent incidents est désactivé dans les paramètres de la page de statut.

Le titre a été tronqué. Les titres sont limités à 200 caractères. Mettez le détail dans le corps.

Il apparaît au mauvais endroit sur la chronologie. La valeur Occurred at est le moment où l'événement s'est produit, pas le moment où vous l'avez écrit. Supprimez et recréez avec l'heure correcte.

Rien n'est listé. Aucune annotation n'a été créée encore. L'état vide vous invite à marquer une version, un incident ou un jalon.

Où aller ensuite

• Orbit Status Page pour publier les incidents à vos clients.
• Orbit Releases pour l'historique des versions basé sur les tags.
• Orbit Project Analytics pour les graphiques que les annotations expliquent.