Orbit Zeitleisten-Anmerkungen

Annotations lassen Sie Kontext auf die Timeline eines Projekts schreiben: der Incident, der um 2 Uhr morgens begann, das Release, das den Checkout-Flow veränderte, das Feature Flag, das jemand umgeschaltet hat. Sechs Monate später sind sie der Unterschied zwischen einem Chart mit einem rätselhaften Sprung und einem Chart, den Sie erklären können.

Wo Annotations zu finden sind

Öffnen Sie Orbit, klicken Sie auf das Projekt, und wählen Sie Timeline unter der Gruppe Observability in der Projektregisterkarte. Die Seite heißt Timeline annotations und beschreibt sich selbst als Kennzeichnung von Incidents, Releases, Milestones und Notizen auf Ihrer Deployment-Timeline.

Die fünf Arten

Flag flip verdient eine eigene Art aus einem bestimmten Grund. Eine Flag-Änderung verändert das Verhalten in der Produktion, ohne ein Deployment zu erzeugen, hinterlässt also keine Spur in der Deployment-Historie. Wenn sich die Leistung an einem Tag ohne Deployments verändert, ist ein Flag flip sehr oft die Antwort, und nur eine Annotation wird Ihnen das zeigen.

Eine Annotation erstellen

1. Klicken Sie auf New annotation.
2. Wählen Sie die Kind aus.
3. Legen Sie Occurred at fest. Der Standardwert ist jetzt, und Sie können eine frühere Zeit eintragen.
4. Schreiben Sie einen Title, bis zu 200 Zeichen.
5. Schreiben Sie optional einen Body, bis zu 4000 Zeichen, für Notizen, Links oder Postmortem-Text.
6. Klicken Sie auf Create.

Das Backdating ist wichtig. Schreiben Sie die Annotation, wenn Sie Zeit haben, und stellen Sie die Zeit auf den Zeitpunkt ein, zu dem das Ereignis tatsächlich passiert ist, damit es am richtigen Ort auf der Timeline erscheint.

Filtern

Die Filterleiste oben bietet All sowie jede Art. Das Filtern auf Incident gibt Ihnen eine Incident-Historie für das Projekt in einer Ansicht, was genau das ist, was Sie brauchen, wenn Sie einen Quarterly Review schreiben oder überprüfen, ob ein wiederkehrendes Problem tatsächlich wiederkehrend ist.

An einen Deployment verankern

Eine Annotation kann an einen bestimmten Deployment gebunden werden, anstatt allein zu stehen. So verbinden Sie eine Folge mit einer Ursache: die Annotation reist mit dem Deployment, der sie verursacht hat.

Verwenden Sie es für das klassische Muster eines Deployments, das gut aussah und eine Stunde später ein Problem verursachte. Verankern Sie den Incident bei diesem Deployment und die Verbindung ist dauerhaft festgehalten, anstatt im Gedächtnis einer Person zu leben.

Incidents werden veröffentlicht

Incident-Annotations sind die Quelle für den Incidents-Bereich Ihrer öffentlichen Statusseite, wenn Sie eine mit Show recent incidents aktiviert haben.

Eine gute Incident-Annotation schreiben

Während des Incidents halten Sie es kurz und sachlich:

• Was ist betroffen, in den Begriffen, die ein Kunde verwenden würde.
• Was Sie wissen, nicht was Sie vermuten.
• Wann Sie das nächste Mal aktualisieren werden.

Fügen Sie anschließend einen Body mit der Auflösung hinzu: was die Ursache war, was sie behoben hat, und was eine Wiederholung verhindert. Das verwandelt die Annotation in ein permanentes Dokument anstelle eines Schnappschusses einer schlimmen Stunde.

Widerstehen Sie dem Drang zu beschönigen. "Checkout war 40 Minuten lang nicht verfügbar" hält besser als "einige Kunden haben möglicherweise intermittierende Probleme erlebt", sowohl als öffentliche Stellungnahme als auch als Ihr eigenes Dokument.

Löschen

Jede Annotation hat eine Lösch-Schaltfläche. Die Bestätigung sagt einfach, dass dies nicht rückgängig gemacht werden kann.

Löschen Sie Tippfehler und Duplikate. Löschen Sie keine Incidents, weil sie peinlich sind: Der Wert der Timeline ist, dass sie vollständig ist, und eine Geschichte mit entfernten schlechten Tagen kann Ihnen nichts über Muster sagen.

Lesen der Timeline gegen Ihre Charts

Annotations zahlen sich aus, wenn Sie sie neben einer Metrik platzieren:

• Eine Stufenänderung bei Web Vitals. Überprüfen Sie die Timeline auf ein Release oder einen Flag flip am gleichen Tag: siehe Orbit Web Vitals.
• Ein Sprung in der Build-Dauer. Suchen Sie nach einem Milestone wie einem Dependency-Upgrade oder einer Monorepo-Umstrukturierung: siehe Orbit Build Insights.
• Eine Anhäufung fehlgeschlagener Deployments. Eine Incident-Annotation erklärt dies normalerweise, und wenn es nicht vorhanden ist, ist dies selbst wissenswert.

Annotations automatisch erstellen

Annotations können über die Orbit API erstellt werden, was bedeutet, dass Ihre eigenen Tools sie schreiben können. Zwei Muster lohnen sich einzurichten:

• Ihr Alerting-System öffnet eine Incident-Annotation, wenn es jemanden alarmiert, sodass die Timeline ohne dass jemand daran denken muss, gefüllt wird.
• Ihr Feature-Flag-Tool schreibt bei jeder Änderung eine Flag flip-Annotation, was die einzig zuverlässige Möglichkeit ist, diesen Datensatz zu führen.

Siehe Orbit API Tokens and the REST API für Authentifizierung und Endpoint-Referenz.

Gewohnheiten, die es wert sind, aufgebaut zu werden

Eine Annotation pro Ereignis, aktualisiert im Body. Nicht fünf Annotations, die denselben Incident nachverfolgen. Die Timeline sollte auf einen Blick lesbar sein.

Kommentieren Sie auch die langweiligen Erfolge. "Images zum Edge verschoben" neben der Woche, in der Ihre Bandbreite sank, ist wie Sie beweisen, dass die Arbeit es wert war.

Schreiben Sie es am gleichen Tag. Eine Annotation, die eine Woche später geschrieben wird, ist vager und normalerweise falsch in Bezug auf die Zeit.

Fehlerbehebung

Die Annotation ist nicht auf der Statusseite. Ihre Art ist nicht Incident, oder der Schalter Show recent incidents ist in den Statusseiten-Einstellungen ausgeschaltet.

Der Titel wurde gekürzt. Titel sind auf 200 Zeichen begrenzt. Geben Sie die Details in den Body ein.

Es erscheint an der falschen Stelle auf der Timeline. Der Wert Occurred at ist, wann das Ereignis passiert ist, nicht wann Sie es geschrieben haben. Löschen und neu erstellen mit der richtigen Zeit.

Nichts ist aufgelistet. Es wurden noch keine Annotations erstellt. Der leere Zustand fordert Sie auf, ein Release, einen Incident oder einen Milestone zu markieren.

Wohin es danach geht

• Orbit Status Page um Incidents für Ihre Kunden zu veröffentlichen.
• Orbit Releases für die Tag-basierte Versionshistorie.
• Orbit Project Analytics für die Charts, die Annotations erklären.