Orbit Tijdlijn Annotaties

Annotaties stellen je in staat context op de timeline van een project te schrijven: het incident dat om 2 uur 's ochtends begon, de release die de checkout-flow veranderde, de feature flag die iemand heeft omgeschakeld. Zes maanden later maken zij het verschil tussen een grafiek met een mysterieuze stap erin en een grafiek die je kunt uitleggen.

Waar annotaties zich bevinden

Open Orbit, klik op het project en kies Timeline onder de groep Observability in de projecttabstrip. De pagina heet Timeline annotations en beschrijft zichzelf als het markeren van incidents, releases, milestones en notities op je implementatietimeline.

De vijf soorten

Flag flip verdient zijn eigen soort om een specifieke reden. Een vlagwijziging verandert het gedrag in productie zonder een implementatie te produceren, dus het laat geen spoor in de implementatiegeschiedenis achter. Wanneer prestaties op een dag zonder implementaties verschuiven, is een flag flip zeer vaak het antwoord, en alleen een annotatie zal je dat vertellen.

Een annotatie maken

1. Klik op New annotation.
2. Kies het Kind.
3. Stel Occurred at in. Het staat standaard op nu, en je kunt het terugdateren.
4. Schrijf een Title, tot 200 tekens.
5. Schrijf optioneel een Body, tot 4000 tekens, voor notities, links of postmortem-tekst.
6. Klik op Create.

Terugdateren is belangrijk. Schrijf de annotatie wanneer je tijd hebt en stel de tijd in op wanneer het ding werkelijk gebeurde, zodat het op de juiste plaats op de timeline terechtkomt.

Filteren

De filterbalk bovenaan biedt All plus elke soort. Filteren naar Incident geeft je een incidentgeschiedenis voor het project in één weergave, wat precies is wat je wilt bij het schrijven van een driemaandelijks overzicht of wanneer je uitzoekt of een terugkerend probleem echt terugkeert.

Verankeren aan een implementatie

Een annotatie kan aan een specifieke implementatie worden gekoppeld in plaats van zelfstandig te bestaan. Op deze manier verbind je een gevolg met een oorzaak: de annotatie reist mee met de implementatie die het veroorzaakte.

Gebruik het voor het klassieke patroon van een implementatie die er goed uitzag en een uur later een probleem veroorzaakte. Zet het incident vast aan die implementatie en de verbinding wordt permanent geregistreerd, in plaats van in iemands geheugen te leven.

Incidents worden gepubliceerd

Incident-annotaties zijn de bron voor de incidenten-sectie van je openbare statuspagina, als je die hebt ingeschakeld met Show recent incidents ingeschakeld.

Een goed incident-annotatie schrijven

Houd het tijdens het incident kort en feitelijk:

• Wat wordt beïnvloed, in termen die een klant zou gebruiken.
• Wat je weet, niet wat je vermoedst.
• Wanneer je volgende update geeft.

Voeg daarna een body toe met de resolutie: wat de oorzaak was, wat het oploste en wat herhaalde occurrence verhindert. Dat maakt de annotatie in plaats van een snapshot van een slecht uur een permanent record.

Weersta de neiging om te verzwakken. "Checkout was 40 minuten niet beschikbaar" wordt beter oud dan "sommige klanten hebben mogelijk onderbrekingen ervaren", zowel als openbare verklaring als in je eigen record.

Verwijderen

Elke annotatie heeft een verwijderingscontrole. De bevestiging zegt eenvoudig dat dit niet ongedaan kan worden gemaakt.

Verwijder typefouten en duplicaten. Verwijder geen incidents omdat ze genant zijn: de waarde van de timeline is dat die compleet is, en een geschiedenis met de slechte dagen eruit verwijderd kan je niets over patronen vertellen.

De timeline tegen je grafieken lezen

Annotaties worden lonend wanneer je ze naast een metriek plaatst:

• Een stap verandering in Web Vitals. Controleer de timeline op een release of een flag flip op dezelfde dag: zie Orbit Web Vitals.
• Een sprong in build-duur. Zoek naar een milestone zoals een dependency-upgrade of een monorepo-herstructurering: zie Orbit Build Insights.
• Een cluster van mislukte implementaties. Een incident-annotatie verklaart het meestal, en als er geen is, is dat op zich al de moeite waard om te weten.

Annotaties automatisch maken

Annotaties kunnen via de Orbit API worden gemaakt, wat betekent dat je eigen tooling deze kan schrijven. Twee patronen zijn het instellen waard:

• Je alertingssysteem opent een Incident-annotatie wanneer het iemand pagineert, zodat de timeline zonder dat iemand eraan moet denken wordt ingevuld.
• Je feature-flag-tooling schrijft een Flag flip-annotatie bij elke wijziging, wat de enige betrouwbare manier is om die record actueel te houden.

Zie Orbit API Tokens and the REST API voor authenticatie en de eindpuntreferentie.

Gewoonten die het waard zijn om op te bouwen

Één annotatie per gebeurtenis, bijgewerkt in de body. Niet vijf annotaties die hetzelfde incident volgen. De timeline moet in een oogopslag leesbaar zijn.

Annoteer ook de saaie winsten. "Afbeeldingen naar de rand verplaatst" naast de week waarin je bandbreedte daalde, is hoe je bewijst dat het werk het waard was.

Schrijf het dezelfde dag. Een annotatie geschreven een week later is vager en meestal verkeerd over de tijd.

Problemen oplossen

De annotatie staat niet op de statuspagina. De soort is niet Incident, of de schakelaar Show recent incidents staat uit in de statuspaginaschema's.

De titel was afgekapt. Titels hebben een maximum van 200 tekens. Zet het detail in de body.

Het verschijnt op de verkeerde plaats op de timeline. De waarde Occurred at is wanneer de gebeurtenis plaatsvond, niet wanneer je deze schreef. Verwijder en maak opnieuw aan met het juiste moment.

Er staat niets vermeld. Er zijn nog geen annotaties gemaakt. De lege status vraagt je om een release, incident of milestone te markeren.

Waar je vervolgens heen gaat

• Orbit Status Page om incidents aan je klanten te publiceren.
• Orbit Releases voor de taggebaseerde versiegeschiedenis.
• Orbit Project Analytics voor de grafieken die annotaties uitleggen.