Документация Grafana Документация GlaberGraph Визуализация данных Дашборды Создание дашбордов Аннотирование визуализаций

Аннотирование визуализаций

Аннотации позволяют отмечать точки на визуализации событиями с расширенным описанием. Они отображаются в виде вертикальных линий и значков на всех панелях-графиках. При наведении курсора на аннотацию можно увидеть описание и теги события. В текстовом поле могут быть ссылки на другие системы с более подробной информацией.

Аннотировать визуализации можно тремя способами:

• Непосредственно на панели с помощью встроенного запроса аннотаций
• Через HTTP API
• Настроив запросы аннотаций

В первых двух случаях вы создаёте новые аннотации, а в последнем запрашиваете существующие аннотации из источников данных. Встроенный запрос аннотаций также поддерживает эту возможность.

На этой странице описаны первый и третий варианты; информацию об использовании HTTP API см. в разделе Annotations API.

Аннотации поддерживаются для следующих типов визуализаций:

• Временные ряды
• Временная шкала состояний
• Свечной график

Создание аннотаций на панелях

Grafana позволяет добавлять события аннотаций непосредственно с панели с помощью встроенного запроса аннотаций, который есть на всех дашбордах. Созданные таким образом аннотации хранятся в Grafana.

Чтобы добавлять аннотации непосредственно на панели:

• Дашборд должен быть уже сохранён.
• Встроенный запрос должен быть включён. Подробнее см. в разделе Встроенный запрос.

Посмотрите короткое видео о создании аннотаций:

Добавление аннотации

Чтобы добавить аннотацию, выполните следующие шаги:

1. Если вы только что сохранили дашборд, обновите страницу.
2. Нажмите на точку данных на панели, чтобы открыть подсказку.
3. В подсказке нажмите Add annotation.
4. Добавьте описание аннотации и теги (необязательно).
5. Нажмите Save.

Кроме того, чтобы добавить аннотацию, нажмите Ctrl/Cmd и щёлкните в любом месте панели — появится подсказка Add annotation.

Добавление аннотации-области

1. Если вы только что сохранили дашборд, обновите страницу.
2. Нажмите Ctrl/Cmd и, удерживая, перетащите курсор по панели, чтобы открыть диалоговое окно Add annotation.
3. Добавьте описание аннотации и теги (необязательно).
4. Нажмите Save

Редактирование аннотации

1. Наведите курсор на индикатор аннотации в нижней части панели, чтобы открыть подсказку.
2. Нажмите значок карандаша, чтобы открыть диалоговое окно аннотации.
3. Измените описание и теги.
4. Нажмите Save.

Удаление аннотации

1. Наведите курсор на индикатор аннотации в нижней части панели, чтобы открыть подсказку.
2. Нажмите значок корзины, чтобы открыть диалоговое окно аннотации.

Запросы аннотаций

Вы можете добавлять новые запросы для получения аннотаций с помощью любого источника данных, включая встроенный источник данных аннотаций. Запросы аннотаций возвращают события, которые можно отобразить в виде маркеров событий на графиках дашборда.

Посмотрите короткое видео ниже.

Добавление запросов аннотаций

Чтобы добавить запрос аннотации в дашборд, выполните следующие шаги:

1. Перейдите к дашборду, который хотите изменить.

2. Нажмите Edit.

3. Нажмите значок Add new element (синий знак «плюс»).

4. Нажмите Annotation query.

5. Введите имя запроса аннотации.

   Это имя присваивается переключателю, позволяющему включать и отключать отображение событий аннотаций из этого запроса.

6. Если вы не хотите использовать запрос аннотации сразу, снимите флажок Enabled.

7. Выберите цвет для маркеров событий аннотации.

8. Выберите один из следующих пунктов в раскрывающемся списке Show annotation controls in, чтобы определить, где отображается аннотация:

   • Above dashboard — переключатель аннотации отображается над дашбордом. Это значение по умолчанию.
   • Controls menu — переключатель аннотации отображается в меню элементов управления дашборда вместо отображения над дашбордом. Меню элементов управления дашборда отображается как кнопка на панели инструментов дашборда.
   • Hidden — переключатель аннотации не отображается на дашборде.

9. Выберите один из следующих пунктов в раскрывающемся списке Show in, чтобы определить панели, на которых отображается аннотация:

   • All panels — аннотации отображаются на всех панелях, поддерживающих аннотации.
   • Selected panels — аннотации отображаются на всех выбранных вами панелях.
   • All panels except — аннотации отображаются на всех панелях, кроме выбранных вами.

10. Чтобы добавить запрос, выполните одно из следующих действий:

    • Нажмите Open query editor, чтобы открыть диалоговое окно Annotation Query, выберите пункт в раскрывающемся списке Data source и напишите или составьте запрос. Параметры запроса аннотации различаются для каждого источника данных. Информацию об аннотациях в конкретном источнике данных см. в соответствующем разделе источника данных. Перейдите к следующему шагу.
    • Нажмите Use saved query, чтобы открыть панель Saved queries. Выберите сохранённый запрос для повторного использования, нажмите Select query и переходите к шагу 13.

Note

Сохранённые запросы доступны только в Grafana Enterprise и Grafana Cloud.

11. (Необязательно) Нажмите Test annotation query, чтобы убедиться, что запрос работает правильно.
12. Нажмите Close, когда завершите настройку запроса.
13. Нажмите Save.
14. (Необязательно) Введите описание внесённых изменений.
15. Нажмите Save.
16. Нажмите Exit edit.

Сохранённые запросы

Вы можете повторно использовать запросы, сохранённые вами и другими сотрудниками организации, в аннотациях. Это помогает пользователям всей организации создавать аннотации, не составляя собственные запросы и не зная языка запросов. Это также избавляет от необходимости нескольким пользователям многократно создавать одинаковые запросы к одним и тем же источникам данных.

Сохранённые запросы поддерживаются в:

• Дашбордах
• Explore
• Аннотациях

Подробнее о сохранённых запросах:

• Диалоговое окно сохранённых запросов
• Роли, разрешения и RBAC
• Переменные в сохранённых запросах
• Управление сохранёнными запросами как кодом
• Известные ограничения

Диалоговое окно сохранённых запросов

Диалоговое окно Saved queries даёт доступ ко всем сохранённым запросам вашей организации:

Чтобы открыть сохранённые запросы, нажмите Use saved query в настройках аннотаций.

В диалоговом окне Saved queries можно:

• Искать запросы по имени источника данных, содержимому запроса, заголовку или описанию.
• Сортировать запросы по алфавиту или по дате создания.
• Фильтровать по имени источника данных, имени автора и тегам. Фильтр по тегам использует оператор OR, а остальные — оператор AND. Используйте переключатель Remember filters, чтобы сохранять выбранные фильтры между сессиями в локальном хранилище.
• Добавлять запросы в избранное, чтобы они отображались в представлении фильтра Starred queries.
• Дублировать или удалять сохранённый запрос.
• Изменять заголовок, описание или теги запроса.

В представлении фильтра Starred queries доступны все те же возможности поиска, фильтрации и сортировки.

Роли, разрешения и RBAC

Сохранённые запросы поддерживают управление доступом на основе ролей. По умолчанию у сохранённых запросов есть две роли RBAC:

• Writer: создание, обновление и удаление всех сохранённых запросов.
• Reader: повторное использование сохранённых запросов.

Если вы использовали сохранённые запросы до появления поддержки RBAC в Grafana v12.4, роли пользователей Grafana сопоставляются следующим образом:

• Admin > Writer
• Editor > Writer
• Viewer > Reader

Переменные в сохранённых запросах

Если сохранённый запрос содержит переменные, вы можете подставить значения переменных в запрос, не изменяя его. Это удобно в средах, где имена переменных или доступные значения различаются между дашбордами.

Исходные переменные можно сопоставить либо с:

• Переменной вашего дашборда
• Пользовательским значением, которое вы вводите

Grafana применяет выбранные значения к запросу перед вставкой его в дашборд. Однако подстановка применяется к запросу только при его повторном использовании, а исходный сохранённый запрос остаётся неизменным.

Управление сохранёнными запросами как кодом

Вы можете управлять сохранёнными запросами как кодом с помощью провайдера Grafana для Terraform, что позволяет версионировать библиотеку запросов и поддерживать её согласованность между экземплярами. Подробнее см. в разделе Управление сохранёнными запросами с помощью Terraform.

Известные ограничения

• При сохранении запроса проверка не выполняется, поэтому можно сохранить некорректный запрос. Перед сохранением следует убедиться, что запрос работает правильно.
• Можно сохранить не более 1000 запросов.

Встроенный запрос

После добавления аннотации она остаётся видимой. Это объясняется встроенным запросом аннотаций, который есть на всех дашбордах. Этот запрос аннотаций получает все события аннотаций, созданные на текущем дашборде и хранящиеся в Grafana, и отображает их на панели, где они были созданы. Сюда же относятся аннотации истории состояний алертов.

По умолчанию встроенный запрос аннотаций использует специальный источник данных -- Grafana --, и ручные аннотации поддерживаются только при использовании этого источника данных. В встроенном запросе аннотаций можно использовать другой источник данных, но тогда с помощью редактора запросов этого источника данных можно будет создавать только автоматические аннотации.

Чтобы добавлять аннотации непосредственно в дашборд, этот запрос должен быть включён.

Чтобы проверить, включён ли встроенный запрос, выполните следующие шаги:

1. Нажмите Edit в правом верхнем углу дашборда.

2. Нажмите значок Dashboard options на панели инструментов.

3. На боковой панели разверните раздел Annotations.

4. Разверните раздел Hidden в разделе аннотаций.

5. Выберите Annotations & Alerts (Built-in query).

6. Проверьте, установлен ли флажок Enabled.

   Если вы не хотите, чтобы аннотации извлекались и отрисовывались, снимите флажок.

7. Нажмите Save.

8. При необходимости введите описание изменений и нажмите Save.

9. Нажмите Exit edit.

При копировании дашборда с помощью функции Save As копия получает новый идентификатор дашборда, поэтому аннотации, созданные на исходном дашборде, больше не отображаются на копии. Их всё ещё можно показывать, если добавить новый Annotation Query и фильтровать по тегам. Однако это работает только в том случае, если у аннотаций на исходном дашборде были теги для фильтрации.

Ниже приведены некоторые параметры запросов, специфичные для встроенного запроса аннотаций.

Фильтрация запросов по тегу

Вы можете создавать новые запросы для получения аннотаций из встроенного запроса аннотаций с помощью источника данных -- Grafana --, установив для параметра Filter by значение Tags.

Grafana также поддерживает автодополнение существующих тегов — укажите хотя бы один тег.

Например, создайте запрос аннотации с именем outages и укажите тег outage. Этот запрос показывает все аннотации (с любого дашборда или через API) с тегом outage. Если в запросе аннотации определено несколько тегов, Grafana показывает только аннотации, соответствующие всем тегам. Чтобы изменить это поведение, включите Match any, и Grafana будет показывать аннотации, содержащие любой из указанных вами тегов.

В запросе по тегам также можно использовать переменные шаблона. Это означает, что если у вас есть дашборд со статистикой по разным сервисам и переменная шаблона, определяющая, какие сервисы показывать, вы можете использовать эту же переменную шаблона в запросе аннотации, чтобы показывать аннотации только для этих сервисов.

Добавление временных областей

При добавлении или редактировании аннотации можно задать повторяющуюся временную область, установив для параметра Query type значение Time regions. Затем определите разделы From и To, указав нужные дни недели и время. Также есть возможность изменить часовой пояс, который по умолчанию совпадает с часовым поясом дашборда.

Приведённая выше конфигурация даёт следующий результат на панели временных рядов:

Включите переключатель Advanced и используйте синтаксис Cron для более точной настройки временных областей. В следующем примере задаётся временная область с 9:00 с понедельника по пятницу: