Orbit
Аннотации временной шкалы Orbit
Annotations let you write context onto a project's timeline: the incident that started at 2am, the release that changed the checkout flow, the feature flag someone flipped. Six months later they are…
Аннотации позволяют добавлять контекст на временную шкалу проекта: инцидент, который произошел в 2 часа ночи, релиз, который изменил процесс оформления покупки, флаг функции, который кто-то переключил. Через полгода они помогут вам отличить график с загадочным скачком от графика, который вы сможете объяснить.
Где находятся аннотации
Откройте Orbit, нажмите на проект и выберите Timeline в группе Observability на вкладке проекта. Страница называется Timeline annotations и описывает себя как инструмент отметки инцидентов, релизов, вех и заметок на временной шкале развертывания.
Пять видов аннотаций
| Вид | Когда использовать |
|---|---|
| Incident | Что-то сломалось. Перебои в работе, деградация производительности, проблемы с данными |
| Release | Значимый релиз, особенно стоящий объяснения |
| Milestone | Момент, достойный記ания: день запуска, первая тысяча пользователей, завершенная миграция |
| Flag flip | Флаг функции включен или выключен, что является изменением, похожим на развертывание, но без развертывания |
| Note | Всё остальное, достойное записи |
Flag flip заслуживает отдельного вида по конкретной причине. Изменение флага меняет поведение в production без развертывания, поэтому оно не оставляет следов в истории развертываний. Когда производительность меняется в день без развертываний, флаг обычно является ответом, и только аннотация это покажет.
Создание аннотации
- Нажмите New annotation.
- Выберите Kind.
- Установите Occurred at. По умолчанию это текущее время, и вы можете установить более раннее время.
- Напишите Title, до 200 символов.
- При необходимости напишите Body, до 4000 символов, для заметок, ссылок или текста постмортема.
- Нажмите Create.
Установка более раннего времени важна. Напишите аннотацию, когда у вас будет время, и установите время на момент, когда это событие действительно произошло, чтобы оно оказалось в нужном месте на временной шкале.
Поместите ответ в заголовок, а не в категорию. "Checkout timing out for AU customers" полезен в списке; "Incident", нет, и значок вида уже это указывает.
Фильтрация
Панель фильтров в верхней части предлагает All плюс каждый вид. Фильтрация по Incident дает вам историю инцидентов для проекта в одном представлении, что точно то, что нужно при написании квартального обзора или определении, действительно ли рекурсивная проблема повторяется.
Привязка к развертыванию
Аннотация может быть привязана к конкретному развертыванию вместо того, чтобы стоять отдельно. Это то, как вы связываете следствие с причиной: аннотация путешествует с развертыванием, которое её вызвало.
Используйте это для классического сценария развертывания, которое выглядело хорошо и вызвало проблему час спустя. Привяжите инцидент к этому развертыванию, и связь будет записана навсегда, вместо того чтобы жить в памяти кого-то.
Инциденты публикуются
Аннотации инцидентов являются источником для раздела инцидентов вашей публичной страницы статуса, если она включена с включенной опцией Show recent incidents.
Предполагайте, что любой может прочитать аннотацию инцидента. Не размещайте в ней имена клиентов, учетные данные, детали внутренних систем или обвинения. Напишите обращенный к клиенту текст в аннотацию инцидента и держите внутренние детали в аннотации-заметке или в собственном документе постмортема. См. Orbit Status Page.
Написание хорошей аннотации инцидента
Во время инцидента держите её короткой и фактической:
- Что затронуто, в терминах, которые используют клиенты.
- Что вы знаете, а не что вы предполагаете.
- Когда вы далее обновите информацию.
После этого добавьте тело с решением: какова была причина, что её исправило, и что предотвратит её повторение. Это превращает аннотацию в постоянную запись вместо снимка плохого часа.
Сопротивляйтесь желанию смягчить. "Checkout был недоступен 40 минут" выглядит лучше с течением времени, чем "некоторые клиенты могли испытать прерывистые проблемы", как публичное заявление, так и ваша собственная запись.
Удаление
У каждой аннотации есть элемент управления удалением. Подтверждение просто говорит, что это не может быть отменено.
Удаляйте опечатки и дубликаты. Не удаляйте инциденты, потому что они неловкие: ценность временной шкалы в том, что она полная, и история с удаленными плохими днями не может ничего рассказать вам о паттернах.
Чтение временной шкалы с вашими графиками
Аннотации окупаются, когда вы размещаете их рядом с метрикой:
- Скачок в Web Vitals. Проверьте временную шкалу на релиз или флаг в тот же день: см. Orbit Web Vitals.
- Скачок в длительности сборки. Ищите вехи, такие как обновление зависимостей или реструктуризация монорепозитория: см. Orbit Build Insights.
- Кластер неудачных развертываний. Аннотация инцидента обычно это объясняет, и если её нет, это само по себе стоит знать.
Автоматическое создание аннотаций
Аннотации могут быть созданы через Orbit API, что означает, что ваш собственный инструмент может их записывать. Два паттерна стоит настроить:
- Ваша система оповещений открывает аннотацию Incident, когда кому-то поступает вызов, поэтому временная шкала заполняется без того, чтобы кто-то помнил это делать.
- Ваш инструмент флагов функций записывает аннотацию Flag flip при каждом изменении, что является единственным надежным способом ведения этой записи.
См. Orbit API Tokens and the REST API для аутентификации и справки по endpoint.
Привычки, стоящие построения
Одна аннотация на событие, обновляемая в теле. Не пять аннотаций, отслеживающих один инцидент. Временная шкала должна быть читаема с первого взгляда.
Аннотируйте и скучные победы. "Перемещены изображения на edge" рядом с неделей, когда полоса пропускания упала, это то, как вы доказываете, что работа была стоящей.
Напишите её в тот же день. Аннотация, написанная неделю спустя, менее точна и обычно неправильна относительно времени.
Устранение неполадок
Аннотация отсутствует на странице статуса. Её вид не Incident, или переключатель Show recent incidents выключен в настройках страницы статуса.
Заголовок был обрезан. Заголовки ограничены 200 символами. Поместите детали в тело.
Она появляется в неправильном месте на временной шкале. Значение Occurred at это время, когда событие произошло, а не когда вы его написали. Удалите и создайте заново с правильным временем.
Ничего не указано. Ещё не созданы аннотации. Пустое состояние побуждает вас отметить релиз, инцидент или веху.
Куда дальше
- Orbit Status Page для публикации инцидентов вашим клиентам.
- Orbit Releases для истории версий на основе тегов.
- Orbit Project Analytics для графиков, которые объясняют аннотации.