Запрос метрик Prometheus с помощью API и PromQL

Управляемая служба Azure Monitor для Prometheus собирает метрики из кластеров Azure Kubernetes и сохраняет их в рабочей области Azure Monitor. Язык запросов Prometheus (PromQL) — это функциональный язык запросов, который можно использовать для запроса и агрегирования данных временных рядов. Используйте PromQL для запроса и агрегирования метрик, хранящихся в рабочей области Azure Monitor.

В этой статье описывается, как запросить рабочую область Azure Monitor с помощью PromQL через REST API. Дополнительные сведения о PromQL см. в разделе "Запрос Prometheus".

Предпосылки

Чтобы запросить рабочую область Azure Monitor с помощью PromQL, вам потребуется:

• Кластер Azure Kubernetes или удаленный кластер Kubernetes.
• Управляемая служба Azure Monitor для сбора метрик Prometheus в кластере Kubernetes.
• Рабочая область Azure Monitor, в которой хранятся метрики Prometheus.

Аутентификация

Чтобы запросить рабочую область Azure Monitor, выполните проверку подлинности с помощью идентификатора Microsoft Entra. API поддерживает проверку подлинности Microsoft Entra с помощью учетных данных клиента. Зарегистрируйте клиентское приложение с идентификатором Microsoft Entra и запросите токен.

Чтобы настроить проверку подлинности Microsoft Entra, выполните следующие действия.

1. Зарегистрируйте приложение с помощью идентификатора Microsoft Entra.
2. Предоставьте приложению доступ к рабочей области Azure Monitor.
3. Запросите токен.

Регистрация приложения с помощью идентификатора Microsoft Entra

Чтобы зарегистрировать приложение, выполните действия, описанные в разделе "Регистрация приложения", чтобы запросить маркеры авторизации и работать с API.

Разрешить приложению доступ к рабочей области

Назначьте роль средства чтения данных мониторинга приложению, чтобы она могли запрашивать данные из рабочей области Azure Monitor.

1. Откройте рабочую область Azure Monitor в портале Azure.

2. На странице обзора запишите конечную точку запроса для использования в запросе REST.

3. Выберите Управление доступом (IAM).

4. На странице управления доступом (IAM) выберите "Добавить>назначение роли".

   

5. На странице Добавить назначение роли найдите Мониторинг.

6. Выберите Читатель данных мониторинга, а затем выберите вкладку Участники.

   

7. Нажмите Выбрать членов.

8. Найдите приложение, которое вы зарегистрировали, и выберите его.

9. Нажмите кнопку "Выбрать".

10. Выберите Рецензирование + Назначение.

    

Вы создали регистрацию приложения и назначили ей доступ к данным запроса из рабочей области Azure Monitor. Теперь вы можете создать токен и использовать его в запросе.

Запрос токена

Отправьте следующий запрос в командной строке или с помощью клиента, например "Бессонница" или команды PowerShell Invoke-RestMethod .

curl -X POST 'https://login.microsoftonline.com/<tenant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret>' \
--data-urlencode 'resource=https://prometheus.monitor.azure.com'

Образец текста ответа

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https:/prometheus.monitor.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Сохраните маркер доступа из ответа для использования в следующих HTTP-запросах.

Конечная точка запроса

Найдите конечную точку запроса рабочей области Azure Monitor на странице обзора рабочей области Azure Monitor.

Поддерживаемые API

Поддерживаются следующие запросы.

Мгновенные запросы

Дополнительные сведения см. в разделе "Мгновенные запросы".

Путь:/api/v1/query

Примеры

POST https://k8s-02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query
--header 'Authorization: Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=sum( \
    container_memory_working_set_bytes \
    * on(namespace,pod) \
    group_left(workload, workload_type) \
    namespace_workload_pod:kube_pod_owner:relabel{ workload_type="deployment"}) by (pod)'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query?query=container_memory_working_set_bytes' 
--header 'Authorization: Bearer <access token>'

Запросы диапазона

Дополнительные сведения см. в разделе "Запросы диапазона".

Путь:/api/v1/query_range

Примеры

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range?query=container_memory_working_set_bytes&start=2023-03-01T00:00:00.000Z&end=2023-03-20T00:00:00.000Z&step=6h'
--header 'Authorization: Bearer <access token>

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/query_range' 
--header 'Authorization: Bearer <access token>'
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'query=up' 
--data-urlencode 'start=2023-03-01T20:10:30.781Z' 
--data-urlencode 'end=2023-03-20T20:10:30.781Z' 
--data-urlencode 'step=6h'

Серия

Дополнительные сведения см. в разделе "Серия".

Путь:/api/v1/series

Примеры

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series' 
--header 'Authorization: Bearer <access token>
--header 'Content-Type: application/x-www-form-urlencoded' 
--data-urlencode 'match[]=kube_pod_info{pod="bestapp-123abc456d-4nmfm"}'

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/series?match[]=container_network_receive_bytes_total{namespace="default-1669648428598"}'

Наклейки

Дополнительные сведения см. в разделе "Метки".

Путь:/api/v1/labels

Примеры

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

POST 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/labels'

Значения меток

Дополнительные сведения см. в разделе "Значения меток".

Путь:/api/v1/label/__name__/values

Замечание

Единственная поддерживаемая версия этого API — __name__это и возвращает все имена метрик. Не поддерживаются никакие другие /api/v1/label/<label_name>/values.

Пример

GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'

Полную спецификацию API Prometheus с открытым исходным кодом см. в разделе HTTP API Prometheus.

Ограничения API

Следующие ограничения являются дополнением к ограничениям, описанным в спецификации Prometheus:

• Все запросы на получение временных рядов (/series или /query или /query_range) должны содержать \_\_name\_\_ метчер меток. То есть каждый запрос должен быть ограничен метрикой. В запросе может быть только один \_\_name\_\_ сопоставитель меток.

• Запрос /series не поддерживает фильтр регулярных выражений.

• Поддерживаемый диапазон времени:

  • /query_range API поддерживает диапазон времени в 32 дня. Этот период времени является допустимым максимальным диапазоном времени, включая селекторы диапазонов, указанные в самом запросе. Например, запрос rate(http_requests_total[1h] за последние 24 часа означает, что данные запрашиваются в течение 25 часов. Это число поступает из диапазона 24 часов плюс 1 час, указанный в самом запросе.
  • /series API извлекает данные в течение максимального 12-часового диапазона времени. Если endTime не предоставлено, то endTime = time.now(). Если диапазон времени больше 12 часов, startTime задается значение endTime – 12h.

• Указанное время начала и окончания с /labels и /label/__name__/values игнорируется. Запрашиваются все сохраненные данные в рабочей области Azure Monitor.

• Экспериментальные функции, такие как примеры, не поддерживаются.

Дополнительные сведения об ограничениях метрик Prometheus см. в разделе метрики Prometheus.

Конфиденциальность регистра

Управляемая служба Azure Monitor для Prometheus является системой, в которой не различаются регистры. Он обрабатывает строки (например, имена метрик, имена меток или значения меток) как те же временные ряды, если они отличаются от других временных рядов только в случае строки.

Замечание

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

В управляемой службе Prometheus следующие временные ряды считаются одинаковыми:

diskSize(cluster="eastus", node="node1", filesystem="usr_mnt")
diskSize(cluster="eastus", node="node1", filesystem="usr_MNT")

Приведенные выше примеры представляют собой один временный ряд в базе данных временных рядов. Действуют следующие ограничения:

• Любые образцы, которые загружаются против них, хранятся так же, как если бы они были собраны или загружены для единой временной серии.
• Если предыдущие примеры принимаются с той же временной меткой, один из них может быть случайно удалён.
• Регистр текста, хранящийся в базе данных временных рядов и возвращаемый запросом, не является предсказуемым. Один и тот же временный ряд может возвращать разные регистры в разное время.
• Любое имя метрики или совпадение имени метки/значения, присутствующие в запросе, извлекаются из базы данных временных рядов путем сравнения без учета регистра. Если в запросе используется механизм сопоставления с учетом регистра, он автоматически обрабатывается как нечувствительный при сравнении строк.

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

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

Часто задаваемые вопросы

В этом разделе приведены ответы на распространенные вопросы.

Мне не хватает всех или некоторых моих метрик. Как устранить проблему?

Используйте руководство по устранению неполадок, чтобы узнать, как собирать метрики Prometheus с менеджируемого агента.

Почему у меня отсутствуют метрики с двумя метками, имеющими одинаковые имена, но разный регистр?

Azure Managed Prometheus — это система, нечувствительная к регистру. Оно обрабатывает строки, такие как имена метрик, имена меток или значения меток, как одинаковые временные ряды, если они отличаются от других временных рядов только по регистру строки. Дополнительные сведения см. в обзоре метрик Prometheus.

Я вижу некоторые пробелы в данных метрик. Почему такое поведение происходит?

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

Это поведение ожидается и не влияет ни на какие из рекомендуемых правил генерации оповещений.

Связанный контент

• Обзор рабочей области Azure Monitor
• Управление рабочей областью Azure Monitor
• Обзор управляемой службы Azure Monitor для Prometheus
• Запрос метрик Prometheus с использованием рабочих книг Azure