API 및 PromQL을 사용하여 Prometheus 메트릭 쿼리

아티클
12/24/2024

Azure Monitor Prometheus용 관리 서비스는 Azure Kubernetes 클러스터에서 메트릭을 수집하여 Azure Monitor 작업 영역에 저장합니다. PromQL(Prometheus 쿼리 언어)은 시계열 데이터를 쿼리하고 집계할 수 있는 기능적 쿼리 언어입니다. PromQL을 사용하여 Azure Monitor 작업 영역에 저장된 메트릭을 쿼리하고 집계합니다.

이 문서에서는 REST API를 통해 PromQL을 사용하여 Azure Monitor 작업 영역을 쿼리하는 방법을 설명합니다. PromQL에 대한 자세한 내용은 prometheus 쿼리를 참조하세요.

필수 조건

PromQL을 사용하여 Azure Monitor 작업 영역을 쿼리하려면 다음 필수 구성 요소가 필요합니다.

Azure Kubernetes 클러스터 또는 원격 Kubernetes 클러스터.
Kubernetes 클러스터에서 메트릭을 스크랩하는 Azure Monitor Prometheus용 관리 서비스입니다.
Prometheus 메트릭이 저장되는 Azure Monitor 작업 영역입니다.

인증

Azure Monitor 작업 영역을 쿼리하려면 Microsoft Entra ID를 사용하여 인증합니다. API는 클라이언트 자격 증명을 사용하여 Microsoft Entra 인증을 지원합니다. Microsoft Entra ID로 클라이언트 앱을 등록하고 토큰을 요청합니다.

Microsoft Entra 인증을 설정하려면 다음 단계를 수행합니다.

Microsoft Entra ID를 사용하여 앱을 등록합니다.
Azure Monitor 작업 영역에 앱에 대한 액세스 권한을 부여합니다.
토큰 요청입니다.

Microsoft Entra ID를 사용하여 앱 등록

앱을 등록하려면 앱을 등록하여 권한 부여 토큰을 요청하고 API를 사용합니다.의 단계를 따릅니다.

앱이 작업 영역에 액세스하도록 허용

Azure Monitor 작업 영역에서 데이터를 쿼리할 수 있도록 앱에 모니터링 데이터 읽기 권한자 역할을 할당합니다.

Azure Portal에서 Azure Monitor 작업 영역을 엽니다.
개요 페이지에서 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'

OSS prom API의 전체 사양은 Prometheus HTTP API를 참조하세요.

API 제한 사항

다음 제한 사항은 Prometheus 사양에 자세히 설명된 제한 사항에 추가됩니다.

쿼리의 범위는 메트릭으로 지정되어야 합니다.
모든 시계열 페치 쿼리(/series, /query 또는 /query_range)에는 __name__ 레이블 검사기가 포함되어야 합니다. 즉, 각 쿼리의 범위는 메트릭으로 지정되어야 합니다. 쿼리에는 하나의 __name__ 레이블 검사기만 있을 수 있습니다.
쿼리/시리즈는 정규식 필터를 지원하지 않습니다.
지원되는 시간 범위
- /query_range API는 32일의 시간 범위를 지원합니다. 이는 쿼리 자체에 지정된 범위 선택기를 포함하여 허용되는 최대 시간 범위입니다. 예를 들어, 지난 24시간 동안의 쿼리 rate(http_requests_total[1h]는 실제로 데이터가 25시간 동안 쿼리되고 있음을 의미합니다. 이는 24시간 범위에 쿼리 자체에 지정된 1시간을 더한 값입니다.
- /series API는 최대 12시간 범위의 데이터를 가져옵니다. endTime이 제공되지 않으면 endTime = time.now()입니다. 시간 범위가 12시간보다 크면 startTime이 endTime – 12h로 설정됩니다.
무시된 시간 범위
/labels 및 /label/__name__/values와 함께 제공된 시작 시간과 종료 시간은 무시되고 Azure Monitor 작업 영역에 보존된 모든 데이터가 쿼리됩니다.
실험적 기능
예시와 같은 실험적 기능은 지원되지 않습니다.

Prometheus 메트릭 제한에 대한 자세한 내용은 Prometheus 메트릭을 참조하세요.

대/소문자 구분

Prometheus용 Azure Monitor 관리형 서비스는 대/소문자를 구분하지 않는 시스템입니다. 문자열의 경우만 다른 시계열과 다른 경우 문자열(예: 메트릭 이름, 레이블 이름 또는 레이블 값)을 동일한 시계열로 처리합니다.

참고 항목

이 동작은 대/소문자를 구분하는 네이티브 오픈 소스 Prometheus와 다릅니다. Azure 가상 머신, 가상 머신 확장 집합 또는 Azure Kubernetes Service 클러스터에서 실행되는 자체 관리형 Prometheus 인스턴스는 대/소문자를 구분하는 시스템입니다.

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용 관리 서비스 개요
Azure 통합 문서를 사용하여 Prometheus 메트릭 쿼리

다음을 통해 공유