Annotazioni della Timeline di Orbit

Le annotazioni ti permettono di scrivere il contesto sulla timeline di un progetto: l'incidente iniziato alle 2 del mattino, il rilascio che ha modificato il flusso di checkout, il feature flag che qualcuno ha attivato. Sei mesi dopo, sono la differenza tra un grafico con un cambio misterioso e un grafico che puoi spiegare.

Dove si trovano le annotazioni

Apri Orbit, fai clic sul progetto e scegli Timeline nel gruppo Observability della barra delle schede del progetto. La pagina è intitolata Timeline annotations e si descrive come contrassegno di incidenti, rilasci, milestone e note sulla timeline di distribuzione.

I cinque tipi

Flag flip merita il suo proprio tipo per un motivo specifico. Un cambio di flag altera il comportamento in produzione senza produrre una distribuzione, quindi non lascia traccia nella cronologia delle distribuzioni. Quando le prestazioni cambiano in un giorno senza distribuzioni, un flag flip è molto spesso la risposta, e solo un'annotazione te lo dirà.

Creazione di un'annotazione

1. Fai clic su New annotation.
2. Scegli il Kind.
3. Imposta Occurred at. Per impostazione predefinita è impostato su adesso e puoi retrodatarlo.
4. Scrivi un Title, fino a 200 caratteri.
5. Facoltativamente scrivi un Body, fino a 4000 caratteri, per note, link o testo postmortem.
6. Fai clic su Create.

La retrodatazione è importante. Scrivi l'annotazione quando hai tempo e imposta l'ora a quando la cosa è effettivamente accaduta, in modo che si trovi nel posto giusto sulla timeline.

Filtro

La barra dei filtri in alto offre All più ogni tipo. Filtrare per Incident ti dà una cronologia degli incidenti per il progetto in una vista, che è esattamente quello che vuoi quando scrivi una revisione trimestrale o stai cercando di capire se un problema ricorrente è effettivamente ricorrente.

Ancoraggio a una distribuzione

Un'annotazione può essere allegata a una distribuzione specifica piuttosto che stare da sola. È così che colleghi una conseguenza a una causa: l'annotazione si sposta con la distribuzione che l'ha causata.

Usalo per il modello classico di una distribuzione che sembrava giusta e ha causato un problema un'ora dopo. Ancora l'incidente a quella distribuzione e la connessione è registrata permanentemente, piuttosto che vivere nella memoria di qualcuno.

Gli incidenti vengono pubblicati

Le annotazioni degli incidenti sono la fonte della sezione degli incidenti della tua pagina di stato pubblica, se ne hai una abilitata con Show recent incidents attivato.

Scrivere una buona annotazione di incidente

Durante l'incidente, mantienilo breve e fattuale:

• Cosa è interessato, nei termini che userebbe un cliente.
• Cosa sai, non quello che sospetti.
• Quando aggiornerai di nuovo.

Successivamente, aggiungi un corpo con la risoluzione: quale era la causa, cosa l'ha risolta e cosa ne impedisce la ricorrenza. Ciò trasforma l'annotazione in un record permanente invece che in uno snapshot di un'ora difficile.

Resisti all'impulso di ammorbidire. "Checkout was unavailable for 40 minutes" invecchia meglio di "some customers may have experienced intermittent issues", sia come dichiarazione pubblica che come tuo record personale.

Eliminazione

Ogni annotazione ha un controllo di eliminazione. La conferma dice semplicemente che non può essere annullata.

Elimina errori di battitura e duplicati. Non eliminare incidenti perché sono imbarazzanti: il valore della timeline è che è completa, e una cronologia con i giorni cattivi rimossi non può dirti nulla sui modelli.

Leggere la timeline rispetto ai tuoi grafici

Le annotazioni si ripagano quando le metti accanto a una metrica:

• Un cambio di step in Web Vitals. Controlla la timeline per un rilascio o un flag flip nello stesso giorno: vedi Orbit Web Vitals.
• Un salto nella durata della compilazione. Cerca una milestone come un aggiornamento delle dipendenze o una ristrutturazione del monorepo: vedi Orbit Build Insights.
• Un cluster di distribuzioni non riuscite. Un'annotazione di incidente di solito la spiega, e se non ce n'è una, anche questo vale la pena di sapere.

Creazione di annotazioni automaticamente

Le annotazioni possono essere create tramite l'API Orbit, il che significa che il tuo strumento personale può scriverle. Due modelli vale la pena configurare:

• Il tuo sistema di avvisi apre un'annotazione Incident quando avverte qualcuno, in modo che la timeline sia compilata senza che nessuno debba ricordarsi di farlo.
• Il tuo strumento di feature flag scrive un'annotazione Flag flip ad ogni modifica, che è l'unico modo affidabile per mantenere quel record.

Vedi Orbit API Tokens and the REST API per l'autenticazione e il riferimento dell'endpoint.

Abitudini che vale la pena sviluppare

Un'annotazione per evento, aggiornata nel corpo. Non cinque annotazioni che seguono lo stesso incidente. La timeline dovrebbe essere leggibile a colpo d'occhio.

Annota anche le vittorie noiose. "Moved images to the edge" accanto alla settimana in cui la tua larghezza di banda è scesa è come provi che il lavoro è valso la pena.

Scrivila lo stesso giorno. Un'annotazione scritta una settimana dopo è più vaga e di solito sbagliata sull'ora.

Risoluzione dei problemi

L'annotazione non è sulla pagina di stato. Il suo tipo non è Incident, oppure l'interruttore Show recent incidents è disattivato nelle impostazioni della pagina di stato.

Il titolo è stato troncato. I titoli sono limitati a 200 caratteri. Metti il dettaglio nel corpo.

Appare nel posto sbagliato sulla timeline. Il valore Occurred at è quando l'evento è accaduto, non quando l'hai scritto. Elimina e ricrea con l'ora giusta.

Non è elencato nulla. Nessuna annotazione è stata ancora creata. Lo stato vuoto ti richiede di contrassegnare un rilascio, un incidente o una milestone.

Dove andare dopo

• Orbit Status Page per pubblicare gli incidenti ai tuoi clienti.
• Orbit Releases per la cronologia delle versioni basata su tag.
• Orbit Project Analytics per i grafici che le annotazioni spiegano.