Документация Grafana Документация GlaberGraph Учебные материалы Начало работы с Grafana Alerting — шаблонизация уведомлений об оповещениях

Это учебное руководство является продолжением руководства Начало работы с Grafana Alerting — группировка уведомлений.

В этом учебном руководстве вы узнаете:

• О двух типах шаблонов в Grafana Alerting: шаблонах меток и аннотаций и шаблонах уведомлений.
• Как настраивать правила оповещения с аннотациями summary и description.
• Как создать шаблон уведомления, который интегрируется с аннотациями правил оповещения.
• Как использовать встроенный шаблон уведомления для группировки и форматирования нескольких экземпляров оповещений.
• Как предварительно просматривать уведомления об оповещениях, используя экземпляры оповещений в полезной нагрузке шаблона уведомления.

Перед началом работы

Существует несколько способов пройти это учебное руководство.

Примечание: некоторые функции шаблонизации в Grafana Alerting, рассматриваемые в этом учебном руководстве, в настоящее время доступны в Grafana Cloud, но ещё не выпущены в версии с открытым исходным кодом (OSS).

• Grafana Cloud

  • Пользователям Grafana Cloud не нужно ничего устанавливать. Создайте бесплатную учётную запись.

  Перейдите к разделу Как работает шаблонизация.

• Интерактивная среда обучения

  • Кроме того, вы можете попробовать этот пример в нашей интерактивной среде обучения: Начало работы с Grafana Alerting — шаблонизация. Это полностью настроенная среда, в которой уже установлены все зависимости.

• Grafana OSS

  • Если вы решили запустить стек Grafana локально, убедитесь, что у вас установлены следующие приложения:

  • Docker Compose (входит в состав Docker for Desktop для macOS и Windows)

  • Git

Настройка стека Grafana (пользователи OSS)

Чтобы продемонстрировать наблюдение за данными с помощью стека Grafana, загрузите и запустите следующие файлы.

1. Клонируйте репозиторий среды учебного руководства.

   Copy

   git clone https://github.com/grafana/tutorial-environment.git

2. Перейдите в каталог, в который вы клонировали репозиторий:

   Copy

   cd tutorial-environment

3. Запустите стек Grafana:

   Copy

   docker compose up -d

   При первом запуске docker compose up -d Docker загружает все необходимые для учебного руководства ресурсы. В зависимости от скорости вашего интернет-соединения это может занять несколько минут.

   Note

   Если на вашей системе уже запущены Grafana, Loki или Prometheus, вы можете увидеть ошибки, потому что Docker-образ пытается использовать порты, которые уже заняты вашими локальными установками. Если это так, остановите службы, а затем снова выполните команду.

Как работает шаблонизация

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

Шаблонизация меток и аннотаций правил оповещения

Метки и аннотации — это ключевые поля, к которым применяются шаблоны. Одним из главных преимуществ использования шаблонизации в аннотациях является возможность включать динамические данные из запросов, позволяя оповещениям отражать информацию в реальном времени, относящуюся к сработавшему условию. Используя шаблонизацию в аннотациях, вы можете настроить содержимое каждого экземпляра оповещения, например включить имена экземпляров и значения метрик, чтобы уведомление стало более информативным.

Шаблоны уведомлений

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

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

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

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

Шаг 1: шаблонизация меток и аннотаций

Теперь, когда мы представили, как работает шаблонизация, перейдём к следующему шагу. Мы проведём вас через создание правила оповещения с аннотацией summary и description. При этом мы включим использование CPU и имена экземпляров, которые мы позже используем в нашем шаблоне уведомления.

Создание правила оповещения

1. Войдите в Grafana:

   • Пользователи Grafana Cloud: войдите через Grafana Cloud.
   • Пользователи OSS: перейдите на http://localhost:3000.

2. Создайте правило оповещения, включающее аннотацию summary и description:

   • Перейдите в Alerts & IRM > Alerting > Alert rules.
   • Нажмите + New alert rule.
   • Введите имя правила оповещения. Назовите его High CPU usage.

3. В разделе Define query an alert condition:

   • Выберите источник данных TestData в раскрывающемся меню.

     TestData включён в демонстрационную среду. Если вы работаете в Grafana Cloud или на собственном локальном экземпляре Grafana, вы можете добавить источник данных через меню Connections.

   • В поле Scenario выберите CSV Content.

   • Скопируйте следующие CSV-данные:

     Copy

     region,cpu-usage,service,instance
     us-west,88,web-server-1,server-01
     us-west,81,web-server-1,server-02
     us-east,79,web-server-2,server-03
     us-east,52,web-server-2,server-04

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

4. Раздел Alert condition:

   • Оставьте Last в качестве значения функции приведения (WHEN) и IS ABOVE 75 в качестве порогового значения, представляющего использование CPU выше 75 %. Это значение, выше которого должно срабатывать правило оповещения.
   • Нажмите Preview alert rule condition, чтобы выполнить запросы.

   Он должен вернуть 3 ряда в состоянии Firing и 1 в состоянии Normal.

5. Раздел добавления папок и меток:

   • В поле Folder нажмите + New folder и введите имя. Например: System metrics. Эта папка будет содержать наши правила оповещения.

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

6. Раздел Set evaluation behaviour:

   • В поле Evaluation group and interval введите имя. Например: High usage.
   • Выберите Evaluation interval (как часто будет оцениваться оповещение). Выберите 1m.
   • Установите pending period равным 0s (ноль секунд), чтобы правило оповещения срабатывало сразу после выполнения условия (это минимизирует время ожидания для демонстрации).
   • Установите Keep firing for равным 0s, чтобы оповещение прекращало срабатывать сразу после того, как условие перестало выполняться.

7. Раздел Configure notifications:

   Выберите, кто должен получать уведомление при срабатывании правила оповещения.

   • Выберите точку контакта. Если у вас нет точек контакта, нажмите View or create contact points.

8. Раздел Configure notification message:

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

   • Аннотация Summary: введите следующий код в качестве значения аннотации:

     Go Copy

     {{- "\n" -}}
     Instance: {{ index $labels "instance" }}
     {{- "\t" -}} Usage: {{ index $values "A"}}%{{- "\n" -}}

     Этот шаблон автоматически добавляет имя экземпляра (из данных $labels) и текущее использование CPU (из $values[“A”]) в сводку оповещения. \t: добавляет пробел табуляции между именем экземпляра и значением. А \n: вставляет новую строку после значения.

     Пример выходных данных:

     Copy

     server-01	88

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

9. Необязательно: добавьте описание, чтобы помочь дежурному инженеру лучше понять, о чём правило оповещения. Например: это оповещение отслеживает использование CPU на всех экземплярах и срабатывает, если любой экземпляр превышает порог использования 75 %.

10. Нажмите Save rule and exit.

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

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

Шаг 2: шаблонизация уведомлений

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

Без шаблона уведомления сообщения об оповещениях включали бы форматирование Grafana по умолчанию (default.message, см. изображение выше).

Добавление шаблона уведомления:

1. Перейдите в Alerts & IRM > Alerting > Contact points.
2. Выберите вкладку Notification Templates.
3. Нажмите + New notification template.
4. Введите имя. Например, instance-cpu-summary.
5. В раскрывающемся меню Add example выберите Print firing and resolved alerts.

Этот шаблон выводит экземпляры оповещений в двух разделах: firing alerts и resolved alerts, и включает только ключевые детали для каждого. Кроме того, он добавляет наши аннотации summary и description.

Copy

{{- /* Example displaying firing and resolved alerts separately in the notification. */ -}}
{{- /* Edit the template name and template content as needed. */ -}}
{{ define "custom.firing_and_resolved_alerts" -}}
{{ len .Alerts.Resolved }} resolved alert(s)
{{ range .Alerts.Resolved -}}
  {{ template "alert.summary_and_description" . -}}
{{ end }}
{{ len .Alerts.Firing }} firing alert(s)
{{ range .Alerts.Firing -}}
  {{ template "alert.summary_and_description" . -}}
{{ end -}}
{{ end -}}
{{ define "alert.summary_and_description" }}
  Summary: {{.Annotations.summary}}
  Status: {{ .Status }}
  Description: {{.Annotations.description}}
{{ end -}}

Вот разбор шаблона:

• Раздел {{ define "custom.firing_and_resolved_alerts" -}}: отображает количество разрешившихся оповещений и их сводки, используя шаблон alert.summary_and_description для включения summary, status и description для каждого оповещения.
• Раздел .Alerts.Firing: аналогично перечисляет количество сработавших экземпляров оповещений и их детали.
• alert.summary_and_description: этот подшаблон извлекает аннотацию summary, настроенную вами ранее.

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

1. Нажмите Edit payload.

2. Нажмите Use existing alert instance.

   Слева должен быть указан список наших правил оповещения.

3. Нажмите на правило оповещения.

4. Выберите экземпляр.

5. Нажмите Add alert data to payload.

   Экземпляр оповещения добавляется в нижнюю часть предварительного просмотра.

6. Нажмите Save.

Когда шаблон уведомления готов, следующим шагом будет применение его к вашей точке контакта, чтобы увидеть его в действии.

Применение шаблона к вашей точке контакта

1. Примените шаблон к вашей точке контакта.
   • Перейдите в Alerts & IRM > Alerting > Contact points.
   • Измените вашу точку контакта.
2. Необязательно раздел настроек email:
   • Нажмите Edit Message.
   • В поле Select notification template найдите custom.firing_and_resolved_alerts.
   • Нажмите Save.
3. Сохраните вашу точку контакта.

Получение уведомлений

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

Примечание: возможно, вам потребуется приостановить оценку правила оповещения и возобновить её, чтобы запустить уведомление.

На снимке экрана видно, как шаблон уведомления группирует экземпляры оповещений в два раздела: firing alerts и resolved alerts. Каждый раздел включает только ключевые детали для каждого оповещения, обеспечивая краткость и целенаправленность сообщения. Кроме того, включены созданные ранее аннотации summary и description, предоставляющие затронутый экземпляр и использование CPU.

Заключение

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

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

• Обзор функций и операторов, используемых в шаблонах:

  • Язык шаблонов уведомлений
  • Язык шаблонов правил оповещения

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

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

Дополнительно в Grafana Alerting: маршрутизация оповещений с помощью динамических меток