Anotaciones de Cronología de Orbit

Las anotaciones te permiten escribir contexto en la cronología de un proyecto: el incidente que comenzó a las 2am, el lanzamiento que cambió el flujo de checkout, la bandera de funcionalidad que alguien activó. Seis meses después, son la diferencia entre un gráfico con un paso misterioso y un gráfico que puedes explicar.

Dónde Viven las Anotaciones

Abre Orbit, haz clic en el proyecto y elige Timeline bajo el grupo Observability en la pestaña del proyecto. La página se titula Timeline annotations y se describe a sí misma como marcando incidentes, lanzamientos, hitos y notas en tu cronología de despliegue.

Los Cinco Tipos

Flag flip merece su propio tipo por una razón específica. Un cambio de bandera altera el comportamiento en producción sin generar un despliegue, por lo que no deja rastro en el historial de despliegues. Cuando el rendimiento se mueve en un día sin despliegues, un flag flip es muy a menudo la respuesta, y solo una anotación te lo dirá.

Crear una Anotación

1. Haz clic en New annotation.
2. Elige el Kind.
3. Establece Occurred at. Por defecto es ahora, y puedes fecharlo con una fecha anterior.
4. Escribe un Title, hasta 200 caracteres.
5. Opcionalmente escribe un Body, hasta 4000 caracteres, para notas, enlaces o texto de postmortem.
6. Haz clic en Create.

Fechar con fecha anterior es importante. Escribe la anotación cuando tengas tiempo y establece la hora a cuando la cosa realmente sucedió, para que caiga en el lugar correcto en la cronología.

Filtrado

La barra de filtros en la parte superior ofrece All más cada tipo. Filtrar por Incident te da un historial de incidentes para el proyecto en una vista, que es exactamente lo que quieres cuando escribes una revisión trimestral o trabajas en si un problema recurrente es realmente recurrente.

Anclarse a un Despliegue

Una anotación puede adjuntarse a un despliegue específico en lugar de estar sola. Así es como vinculas una consecuencia a una causa: la anotación viaja con el despliegue que la causó.

Úsalo para el patrón clásico de un despliegue que se veía bien y causó un problema una hora después. Ancla el incidente a ese despliegue y la conexión se registra permanentemente, en lugar de vivir en la memoria de alguien.

Los Incidentes Se Publican

Las anotaciones de incidentes son la fuente para la sección de incidentes de tu página de estado pública, si tienes una habilitada con Show recent incidents activado.

Escribir una Buena Anotación de Incidente

Durante el incidente, mantenlo breve y factual:

• Qué se ve afectado, en los términos que usaría un cliente.
• Lo que sabes, no lo que sospechas.
• Cuándo actualizarás a continuación.

Después, agrega un cuerpo con la resolución: cuál fue la causa, qué la arregló y qué evita que se repita. Eso convierte la anotación en un registro permanente en lugar de una instantánea de una hora mala.

Resiste la tentación de suavizar. "Checkout estuvo no disponible durante 40 minutos" envejece mejor que "algunos clientes pueden haber experimentado problemas intermitentes", tanto como declaración pública como en tu propio registro.

Eliminar

Cada anotación tiene un control de eliminar. La confirmación simplemente dice que esto no se puede deshacer.

Elimina errores de escritura y duplicados. No elimines incidentes porque sean vergonzosos: el valor de la cronología es que está completa, y un historial con los días malos eliminados no puede decirte nada sobre patrones.

Leyendo la Cronología Contra Tus Gráficos

Las anotaciones se rentabilizan cuando las pones junto a una métrica:

• Un cambio escalonado en Web Vitals. Verifica la cronología para un lanzamiento o un cambio de bandera el mismo día: ver Orbit Web Vitals.
• Un salto en la duración de construcción. Busca un hito como una actualización de dependencia o una reestructuración de monorepo: ver Orbit Build Insights.
• Un grupo de despliegues fallidos. Una anotación de incidente generalmente lo explica, y si no hay una, eso en sí mismo vale la pena saber.

Crear Anotaciones Automáticamente

Las anotaciones se pueden crear a través de la API de Orbit, lo que significa que tu propia herramienta puede escribirlas. Hay dos patrones que vale la pena configurar:

• Tu sistema de alertas abre una anotación Incident cuando hace un llamado a alguien, por lo que la cronología se completa sin que nadie tenga que recordar hacerlo.
• Tu herramienta de bandera de funcionalidad escribe una anotación Flag flip en cada cambio, que es la única forma confiable de mantener ese registro.

Ver Orbit API Tokens and the REST API para autenticación y referencia de endpoint.

Hábitos que Vale la Pena Desarrollar

Una anotación por evento, actualizada en el cuerpo. No cinco anotaciones rastreando el mismo incidente. La cronología debe ser legible de un vistazo.

Anota también los logros aburridos. "Movimos imágenes al borde" junto a la semana en que tu ancho de banda cayó es cómo pruebas que el trabajo valía la pena.

Escríbelo el mismo día. Una anotación escrita una semana después es más vaga y generalmente incorrecta sobre la hora.

Solución de Problemas

La anotación no está en la página de estado. Su tipo no es Incident, o el interruptor Show recent incidents está apagado en la configuración de la página de estado.

El título fue truncado. Los títulos tienen un límite de 200 caracteres. Pon el detalle en el cuerpo.

Aparece en el lugar incorrecto en la cronología. El valor Occurred at es cuándo sucedió el evento, no cuándo lo escribiste. Elimina y recrea con la hora correcta.

Nada aparece en la lista. Aún no se han creado anotaciones. El estado vacío te invita a marcar un lanzamiento, incidente o hito.

A Dónde Ir a Continuación

• Orbit Status Page para publicar incidentes a tus clientes.
• Orbit Releases para el historial de versiones basado en etiquetas.
• Orbit Project Analytics para los gráficos que las anotaciones explican.