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

Аннотации Microsoft SQL Server

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

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

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

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

• Настроенный источник данных Microsoft SQL Server
• Таблица, содержащая данные о событиях, как минимум со столбцом времени и столбцом описания
• Знакомство с синтаксисом запросов T-SQL

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

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

1. Перейдите на ваш дашборд и нажмите Dashboard settings (значок шестерёнки).
2. Выберите Annotations в левом меню.
3. Нажмите Add annotation query.
4. Введите Name для аннотации.
5. Выберите ваш источник данных Microsoft SQL Server из раскрывающегося списка Data source.
6. Напишите SQL-запрос, возвращающий требуемые столбцы.
7. Нажмите Save dashboard.

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

Ваш запрос аннотации должен возвращать столбцы с определёнными именами. Grafana использует эти имена для сопоставления результатов запроса с полями аннотации.

Пример: аннотация с временем epoch

Дана таблица, которая хранит события с метками времени Unix epoch:

SQL Copy

CREATE TABLE [events] (
  time_sec bigint,
  description nvarchar(100),
  tags nvarchar(100),
)

Запрос для отображения событий в виде аннотаций:

SQL Copy

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

Макрос $__unixEpochFilter автоматически фильтрует события по выбранному диапазону времени дашборда.

Пример: аннотация-область с временем начала и окончания

Чтобы отображать аннотации в виде затенённых областей (охватывающих некоторую длительность), включите оба столбца time и timeend:

SQL Copy

SELECT
  time_sec as time,
  time_end_sec as timeend,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
ORDER BY 1

Пример: аннотация с собственным столбцом datetime

Если ваша таблица использует собственные столбцы SQL datetime или datetime2 вместо значений epoch:

SQL Copy

SELECT
  time,
  measurement as text,
  convert(varchar, valueOne) + ',' + convert(varchar, valueTwo) as tags
FROM
  metric_values
WHERE
  $__timeFilter(time)
ORDER BY 1

Макрос $__timeFilter работает с собственными типами даты/времени SQL и фильтрует по диапазону времени дашборда.

Пример: аннотации развёртываний

Отображайте события развёртываний на ваших графиках:

SQL Copy

SELECT
  deployed_at as time,
  'Deployed ' + version + ' to ' + environment as [text],
  environment as tags
FROM
  [deployments]
WHERE
  $__timeFilter(deployed_at)
ORDER BY 1

Пример: аннотации окон обслуживания

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

SQL Copy

SELECT
  start_time as time,
  end_time as timeend,
  'Maintenance: ' + description as [text],
  'maintenance' as tags
FROM
  [maintenance_windows]
WHERE
  $__timeFilter(start_time)
ORDER BY 1

Использование переменных шаблонов

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

SQL Copy

SELECT
  time_sec as time,
  description as [text],
  tags
FROM
  [events]
WHERE
  $__unixEpochFilter(time_sec)
  AND server IN ($server)
ORDER BY 1

Макросы

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

Полный список доступных макросов см. в разделе Microsoft SQL Server query editor.

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

При создании аннотаций Microsoft SQL Server следуйте этим рекомендациям:

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

Получение помощи

Если ваши аннотации не отображаются или ведут себя не так, как ожидалось, см. раздел Troubleshoot Microsoft SQL Server data source issues для типовых решений.