Аннотации Amazon CloudWatch

Аннотации накладывают насыщенную информацию о событиях поверх графиков. С источником данных Amazon CloudWatch аннотации основаны на истории CloudWatch alarms. Каждый элемент истории alarm в пределах диапазона времени дашборда — например, изменение состояния, обновление конфигурации или действие — становится аннотацией, что позволяет сопоставлять активность alarms с остальными данными вашего дашборда.

Прежде чем начать

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

Настроенный источник данных Amazon CloudWatch.
Один или несколько CloudWatch alarms в учётной записи и регионе AWS, которые вы хотите запрашивать.
Разрешения IAM на описание alarms и истории alarms. См. раздел Необходимые разрешения.

Как работают аннотации CloudWatch

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

Сопоставление alarms по метрике: Grafana вызывает cloudwatch:DescribeAlarmsForMetric, чтобы найти alarms, привязанные к конкретной метрике.
Сопоставление alarms по префиксу: Grafana вызывает cloudwatch:DescribeAlarms с вашими префиксами имени alarm и действия, так что AWS возвращает только те alarms, имена и действия которых начинаются с этих префиксов. Затем Grafana фильтрует возвращённые alarms по указанным вами namespace, имени метрики, dimensions, statistic и period.

Каждая аннотация включает имя alarm в качестве заголовка, тип элемента истории alarm в качестве тега (например, StateUpdate, ConfigurationUpdate или Action) и сводку истории в качестве текста.

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

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

Откройте дашборд, в который хотите добавить аннотации.
Нажмите Edit, затем нажмите Settings в верхней навигации.
Выберите вкладку Annotations.
Нажмите Add annotation query.
Введите Name для аннотации, например CloudWatch alarms.
Выберите ваш источник данных Amazon CloudWatch.
Настройте поля запроса, описанные в следующих разделах.
Нажмите Save dashboard.

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

Поле	Описание
Region	Регион AWS, в котором выполняется запрос alarms.
Namespace	Namespace метрики, например `AWS/EC2`.
Metric name	Имя метрики, за которой следит alarm, например `CPUUtilization`.
Statistic	Statistic, используемая alarm, например `Average`.
Dimensions	Dimensions, идентифицирующие ресурс, например `InstanceId`.
Period	Необязательно. Минимальный интервал между точками данных в секундах. По умолчанию `300`, когда сопоставление по префиксу отключено.
Enable Prefix Matching	Необязательно. Сопоставлять alarms по имени и префиксу действия вместо метрики.
Action	Сопоставлять только alarms, действия которых начинаются с этого префикса. Доступно при включённом сопоставлении по префиксу и обязательно для выполнения запроса.
Alarm Name	Сопоставлять только alarms, имена которых начинаются с этого префикса. Доступно при включённом сопоставлении по префиксу и обязательно для выполнения запроса.

Сопоставление alarms по метрике

Это поведение по умолчанию, используется, когда Enable Prefix Matching выключено. Grafana возвращает аннотации для любого alarm, привязанного к указанной вами метрике.

При сопоставлении по метрике Region, Namespace, Metric name и Statistic обязательны. Если какое-либо из них отсутствует, запрос возвращает ошибку invalid annotations query. Dimensions необязательны, но их добавление сужает результаты до alarms конкретного ресурса.

Например, чтобы аннотировать историю alarm загрузки CPU на одном экземпляре EC2, задайте:

Region: us-east-1
Namespace: AWS/EC2
Metric name: CPUUtilization
Statistic: Average
Dimensions: InstanceId = i-0123456789abcdef0

Сопоставление alarms по префиксу

Включите Enable Prefix Matching, чтобы находить alarms по имени и префиксу действия, а не по конкретной метрике. Grafana запрашивает до 100 alarms из cloudwatch:DescribeAlarms, используя префиксы Alarm Name и Action, а затем фильтрует возвращённые alarms по указанным вами namespace, имени метрики, dimensions, statistic и period. Для выполнения запроса необходимо указать как префикс Alarm Name, так и префикс Action.

Используйте сопоставление по префиксу, когда хотите вывести группу связанных alarms, например все production-alarms, запускающие определённое действие SNS. Для этого включите Enable Prefix Matching, затем задайте для Alarm Name значение prod-, а для Action — префикс ARN вашего SNS-топика, например arn:aws:sns:us-east-1:123456789012:prod-.

Необходимые разрешения

Запросы аннотаций требуют следующих действий API CloudWatch в политике IAM, прикреплённой к роли или пользователю, от имени которых работает источник данных:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowReadingAlarmsFromCloudWatch",
      "Effect": "Allow",
      "Action": ["cloudwatch:DescribeAlarms", "cloudwatch:DescribeAlarmsForMetric", "cloudwatch:DescribeAlarmHistory"],
      "Resource": "*"
    }
  ]
}

Политика IAM для метрик на странице настройки уже включает эти действия.

Устранение неполадок с аннотациями

Если аннотации не отображаются, как ожидается, попробуйте следующие решения.

Аннотации не отображаются

Убедитесь, что у alarm были изменения состояния в пределах диапазона времени дашборда. Аннотации берутся из истории alarms, поэтому alarm, который никогда не менял состояние, не создаёт аннотаций.
Убедитесь, что Region, Namespace, Metric name, Statistic и Dimensions точно соответствуют существующему alarm.
Проверьте, что роль или пользователь IAM обладает разрешениями cloudwatch:DescribeAlarms, cloudwatch:DescribeAlarmsForMetric и cloudwatch:DescribeAlarmHistory.

Ошибка `invalid annotations query`

Эта ошибка появляется, когда сопоставление по префиксу отключено и запрос доходит до бэкенда с пустыми Region, Namespace, Metric name или Statistic. Укажите все четыре поля либо включите Enable Prefix Matching.
В редакторе аннотаций дашборда неполный запрос метрики часто молча пропускается и не создаёт аннотаций вместо возврата этой ошибки. Если вы не видите аннотаций, убедитесь, что заданы все обязательные поля.