Anotações da Linha Cronológica do Orbit

Annotations permitem escrever contexto na timeline de um projeto: o incidente que começou às 2 da manhã, o lançamento que alterou o fluxo de checkout, o feature flag que alguém ativou. Seis meses depois, são a diferença entre um gráfico com um passo misterioso e um gráfico que consegue explicar.

Onde as Annotations Vivem

Abra o Orbit, clique no projeto e escolha Timeline no grupo Observability na fita de separadores do projeto. A página intitula-se Timeline annotations e descreve-se como marcação de incidentes, lançamentos, marcos e notas na sua timeline de implementação.

Os Cinco Tipos

Flag flip merece o seu próprio tipo por uma razão específica. Uma alteração de flag modifica o comportamento em produção sem produzir um deployment, portanto não deixa qualquer traço no histórico de deploys. Quando o desempenho muda num dia sem deploys, um flag flip é muito frequentemente a resposta, e apenas uma annotation o dirá.

Criar uma Annotation

1. Clique em New annotation.
2. Escolha o Kind.
3. Defina Occurred at. Por padrão, está definido para agora, e pode retroceder no tempo.
4. Escreva um Title, até 200 caracteres.
5. Opcionalmente escreva um Body, até 4000 caracteres, para notas, ligações ou texto de postmortem.
6. Clique em Create.

Retroceder no tempo importa. Escreva a annotation quando tiver tempo, e defina a hora para quando a coisa realmente aconteceu, para que apareça no lugar correto na timeline.

Filtragem

A barra de filtro no topo oferece All mais cada tipo. Filtrar para Incident dá-lhe um histórico de incidentes para o projeto numa única vista, que é exatamente o que quer ao escrever uma revisão trimestral ou ao descobrir se um problema recorrente é realmente recorrente.

Ancorar a um Deployment

Uma annotation pode estar anexada a um deployment específico em vez de estar sozinha. É assim que liga uma consequência a uma causa: a annotation viaja com o deployment que a causou.

Use-o para o padrão clássico de um deploy que parecia bem e causou um problema uma hora depois. Ancorize o incidente a esse deployment e a ligação fica registada permanentemente, em vez de viver apenas na memória de alguém.

Incidents São Publicados

As annotations de incidentes são a origem para a secção de incidentes da sua página de estado pública, se a tiver ativada com Show recent incidents ligado.

Escrever uma Boa Annotation de Incidente

Durante o incidente, mantenha-a curta e factual:

• O que é afetado, nos termos que um cliente usaria.
• O que sabe, não o que suspeita.
• Quando atualizará a seguir.

Depois, adicione um body com a resolução: qual foi a causa, o que a resolveu e o que evita que recorra. Isto transforma a annotation num registo permanente em vez de um instantâneo de uma hora má.

Resista ao impulso de suavizar. "Checkout esteve indisponível durante 40 minutos" envelhece melhor do que "alguns clientes podem ter experimentado problemas intermitentes", tanto como declaração pública como no seu próprio registo.

Eliminar

Cada annotation tem um controlo de eliminação. A confirmação diz simplesmente que isto não pode ser desfeito.

Elimine erros de digitação e duplicatas. Não elimine incidentes porque são vergonhosos: o valor da timeline é que é completa, e um histórico com os dias maus removidos não pode dizer-lhe nada sobre padrões.

Ler a Timeline Contra os Seus Gráficos

As annotations compensam quando as coloca ao lado de uma métrica:

• Uma alteração de passo em Web Vitals. Verifique a timeline para um release ou um flag flip no mesmo dia: consulte Orbit Web Vitals.
• Um salto na duração de compilação. Procure um marco como uma atualização de dependência ou uma reestruturação de monorepo: consulte Orbit Build Insights.
• Um aglomerado de deploys falhados. Uma annotation de incidente geralmente explica-o, e se não houver uma, isso em si é digno de saber.

Criar Annotations Automaticamente

As annotations podem ser criadas através da Orbit API, o que significa que a sua própria ferramenta pode escrevê-las. Dois padrões valem a pena configurar:

• O seu sistema de alertas abre uma annotation Incident quando alerta alguém, para que a timeline seja preenchida sem que ninguém tenha que se lembrar de o fazer.
• A sua ferramenta de feature flag escreve uma annotation Flag flip em cada alteração, que é a única forma fiável de manter esse registo.

Consulte Orbit API Tokens and the REST API para autenticação e referência de endpoint.

Hábitos Dignos de Construir

Uma annotation por evento, atualizada no body. Não cinco annotations a rastrear o mesmo incidente. A timeline deve ser legível num relance.

Anotize também as vitórias chatas. "Movidas imagens para a edge" ao lado da semana em que a sua largura de banda caiu é como prova que o trabalho valia a pena.

Escreva-o no mesmo dia. Uma annotation escrita uma semana depois é mais vaga e geralmente incorreta quanto ao tempo.

Resolução de Problemas

A annotation não está na página de estado. O seu tipo não é Incident, ou o comutador Show recent incidents está desligado nas definições da página de estado.

O título foi truncado. Os títulos têm limite de 200 caracteres. Coloque o detalhe no body.

Aparece no lugar errado na timeline. O valor Occurred at é quando o evento aconteceu, não quando o escreveu. Elimine e recrie com a hora correta.

Nada está listado. Nenhuma annotation foi criada ainda. O estado vazio avisa-o para marcar um release, incidente ou marco.

Onde Ir a Seguir

• Orbit Status Page para publicar incidentes para os seus clientes.
• Orbit Releases para o histórico de versão baseado em tags.
• Orbit Project Analytics para os gráficos que as annotations explicam.