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

2025-04-30

Управляемая служба Azure Monitor для Prometheus собирает метрики из кластеров Azure Kubernetes и сохраняет их в рабочей области Azure Monitor. PromQL (язык запросов Prometheus) — это функциональный язык запросов, позволяющий запрашивать и агрегировать данные временных рядов. Используйте 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, выполните следующие действия.

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

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

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

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

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

Откройте рабочую область Azure Monitor в портале Azure.
На странице обзора запишите конечную точку запроса для использования в запросе REST.
Выберите Управление доступом (IAM).
Выберите "Добавить", а затем на странице управления доступом (IAM) добавьте назначение ролей .
На странице "Добавление назначения ролей" найдите Мониторинг.
Выберите средство чтения данных мониторинга, а затем перейдите на вкладку "Участники".
Выберите "Выбрать участников".
Найдите приложение, которое вы зарегистрировали, и выберите его.
Нажмите кнопку "Выбрать".
Выберите Рецензирование + Назначение.

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

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

Отправьте следующий запрос в командной строке или с помощью клиента, например Insomnia или 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..

Замечание

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

Пример:

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

Полные спецификации API-интерфейсов prom OSS см. в разделе HTTP API Prometheus.

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

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

Запрос должен быть ограничен метрикой.

Запросы на получение временных рядов (/series или /query или /query_range) должны содержать элемент сопоставления метки __name__. То есть каждый запрос должен быть ограничен метрикой. В запросе может быть только один __name__ сопоставитель меток.
Запрос /серия не поддерживает фильтр регулярных выражений
Поддерживаемый диапазон времени
- API /query_range поддерживает диапазон времени в 32 дня. Это максимальный диапазон времени, включая селекторы диапазонов, указанные в самом запросе. Например, запрос rate(http_requests_total[1h] за последние 24 часа фактически означает, что данные запрашиваются в течение 25 часов. Это происходит из 24-часового диапазона плюс 1 час, указанный в самом запросе.
- API /series извлекает данные для максимального диапазона времени в 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 Prometheus — это система, нечувствительная к регистру. Оно обрабатывает строки, такие как имена метрик, имена меток или значения меток, как одинаковые временные ряды, если они отличаются от других временных рядов только по регистру строки. Дополнительные сведения см. в обзоре метрик Prometheus.

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

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

Дальнейшие шаги

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

Поделиться через

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

Предпосылки

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

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

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

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

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

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

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

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

Серия

Наклейки

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

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

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

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

У меня отсутствуют все или некоторые из моих показателей. Как устранить проблему?

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

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

Дальнейшие шаги

Обратная связь

Дополнительные ресурсы