Документация Grafana Документация GlaberGraph Источники данных PostgreSQL Аннотации

Аннотации PostgreSQL

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

Общую информацию об аннотациях см. в разделе Аннотирование визуализаций.

Перед началом

Перед созданием аннотаций PostgreSQL убедитесь, что у вас есть:

• Настроенный источник данных PostgreSQL.
• Таблицы, содержащие данные о событиях с полями временных меток.
• Доступ на чтение к таблицам, содержащим ваши события.

Создание запроса аннотации

Чтобы добавить аннотацию PostgreSQL на ваш дашборд:

1. Перейдите к дашборду, который хотите обновить, и нажмите Edit.
2. Нажмите значок Add new element (синий знак плюс).
3. Нажмите Annotation query.
4. Введите имя для запроса аннотации.
5. Если вы не хотите сразу использовать запрос аннотации, снимите флажок Enabled.
6. Выберите цвет для маркеров событий аннотации.
7. Выберите опцию в раскрывающемся списке Show annotation controls in, чтобы управлять тем, где на дашборде отображается аннотация.
8. Выберите опцию в раскрывающемся списке Show in, чтобы управлять тем, на каких панелях отображается аннотация.
9. Нажмите Open query editor, чтобы открыть диалоговое окно Annotation Query.
10. Выберите ваш источник данных PostgreSQL в раскрывающемся списке Data source.
11. Настройте запрос аннотации и сопоставления полей.
12. (Необязательно) Нажмите Test annotation query, чтобы убедиться, что запрос работает правильно.
13. Нажмите Close, когда завершите настройку запроса.
14. Нажмите Save.
15. (Необязательно) Введите описание внесённых изменений.
16. Нажмите Save.
17. Нажмите Exit edit.

Столбцы запроса

Ваш запрос аннотации должен возвращать столбец time и может дополнительно включать столбцы timeend, text и tags.

Примеры запросов

В следующих примерах показаны распространённые шаблоны запросов аннотаций.

Базовая аннотация со временем epoch

Отображение событий с использованием временных меток UNIX epoch:

SQL Copy

SELECT
  epoch_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__unixEpochFilter(epoch_time)

Аннотация диапазона с начальным и конечным временем

Отображение событий с длительностью в виде затенённых областей:

SQL Copy

SELECT
  epoch_time as time,
  epoch_time_end as timeend,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__unixEpochFilter(epoch_time)

Аннотация с нативным типом даты/времени SQL

Отображение событий с использованием нативных столбцов даты/времени PostgreSQL:

SQL Copy

SELECT
  native_date_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM public.test_data
WHERE $__timeFilter(native_date_time)

Аннотации развёртываний

Отображение событий развёртывания:

SQL Copy

SELECT
  deployed_at as time,
  concat('Deployed ', version, ' to ', environment) as text,
  environment as tags
FROM deployments
WHERE $__timeFilter(deployed_at)

Аннотация диапазона для окон обслуживания

Отображение окон обслуживания в виде затенённых областей:

SQL Copy

SELECT
  start_time as time,
  end_time as timeend,
  concat('Maintenance: ', description) as text,
  'maintenance' as tags
FROM maintenance_windows
WHERE $__timeFilter(start_time)

Макросы

Используйте эти макросы в ваших запросах аннотаций для фильтрации по диапазону времени дашборда:

Рекомендации

Следуйте этим рекомендациям при создании аннотаций PostgreSQL:

• Используйте фильтры времени: всегда включайте $__timeFilter() или $__unixEpochFilter(), чтобы ограничить результаты диапазоном времени дашборда.
• Поддерживайте эффективность запросов: добавьте индексы на столбцы времени и фильтруемые столбцы, чтобы повысить производительность запросов.
• Используйте содержательный текст: включайте описательную информацию в столбец text, чтобы аннотации были полезными.
• Организуйте с помощью тегов: используйте согласованные значения тегов для категоризации аннотаций и включения фильтрации.
• Сначала протестируйте запросы: проверьте, что ваш запрос возвращает ожидаемые результаты в Explore, прежде чем добавлять его как аннотацию.