Prometheus용 Azure Monitor 관리형 서비스는 Azure Kubernetes 클러스터에서 메트릭을 수집하고 Azure Monitor 작업 영역에 저장합니다. PromQL(Prometheus 쿼리 언어)은 시계열 데이터를 쿼리하고 집계하는 데 사용할 수 있는 기능 쿼리 언어입니다. PromQL을 사용하여 Azure Monitor 작업 영역에 저장된 메트릭을 쿼리하고 집계합니다.
이 문서에서는 REST API를 통해 PromQL을 사용하여 Azure Monitor 작업 영역을 쿼리하는 방법을 설명합니다. PromQL에 대한 자세한 내용은 Query Prometheus를 참조하세요.
Prerequisites
PromQL을 사용하여 Azure Monitor 작업 영역을 쿼리하려면 다음이 필요합니다.
- Azure Kubernetes 클러스터 또는 원격 Kubernetes 클러스터.
- Kubernetes 클러스터에서 메트릭을 스크랩하는 Azure Monitor Prometheus용 관리 서비스입니다.
- Prometheus 메트릭이 저장되는 Azure Monitor 작업 영역입니다.
Authentication
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) 페이지에서역할 할당 추가>를 선택합니다.
역할 할당 추가 페이지에서 모니터링을 검색합니다.
모니터링 데이터 판독기를 선택한 다음 멤버 탭을 선택합니다.
멤버 선택을 선택합니다.
등록한 앱을 검색하여 선택합니다.
Choose Select.
검토 + 할당을 선택합니다.
앱 등록을 만들고 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 요청에 사용할 응답의 액세스 토큰을 저장합니다.
Query endpoint
Azure Monitor 작업 영역 개요 페이지에서 Azure Monitor 작업 영역의 쿼리 엔드포인트를 찾습니다.
Supported APIs
지원되는 쿼리는 다음과 같습니다.
Instant queries
자세한 내용은 인스턴트 쿼리를 참조하세요.
Path:/api/v1/query
Examples
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>'
Range queries
자세한 내용은 범위 쿼리를 참조하세요.
Path:/api/v1/query_range
Examples
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'
Series
자세한 내용은 Series를 참조하세요.
Path:/api/v1/series
Examples
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"}'
Labels
자세한 내용은 레이블을 참조하세요.
Path:/api/v1/labels
Examples
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'
Label values
자세한 내용은 레이블 값을 참조하세요.
Path:/api/v1/label/__name__/values
Note
이 API __name__의 유일하게 지원되는 버전은 모든 메트릭 이름을 반환합니다. 다른 /api/v1/label/<label_name>/values 지원되지 않습니다.
Example
GET 'https://k8s02-workspace-abcd.eastus.prometheus.monitor.azure.com/api/v1/label/__name__/values'
오픈 소스 소프트웨어 Prometheus API의 전체 사양은 Prometheus HTTP API를 참조하세요.
API limitations
다음 제한 사항은 Prometheus 사양에 설명된 제한 사항 외에 다음과 같습니다.
시계열 페치 쿼리(
/series또는/query또는/query_range)에는 반드시\_\_name\_\_레이블 매처가 포함되어야 합니다. 즉, 각 쿼리의 범위는 메트릭으로 지정되어야 합니다. 쿼리에는\_\_name\_\_레이블 검사기가 하나만 있을 수 있습니다.쿼리
/series는 정규식 필터를 지원하지 않습니다.지원되는 시간 범위:
- API는
/query_range32일의 시간 범위를 지원합니다. 이 기간은 쿼리 자체에 지정된 범위 선택기를 포함하여 허용되는 최대 시간 범위입니다. 예를 들어 지난 24시간 동안의 쿼리rate(http_requests_total[1h]는 데이터가 25시간 동안 쿼리됨을 의미합니다. 이 숫자는 24시간 범위와 쿼리 자체에 지정된 1시간에서 가져옵니다. - API는
/series최대 12시간 범위의 데이터를 가져옵니다.endTime가 제공되지 않으면endTime = time.now(). 시간 범위가 12시간을 초과하면startTime가endTime – 12h로 설정됩니다.
- API는
제공된
/labels/label/__name__/values시작 시간과 종료 시간은 무시됩니다. Azure Monitor 작업 영역의 모든 보존된 데이터를 쿼리합니다.예시와 같은 실험적 기능은 지원되지 않습니다.
Prometheus 메트릭 제한에 대한 자세한 내용은 Prometheus 메트릭을 참조하세요.
Case sensitivity
Prometheus용 Azure Monitor 관리 서비스는 대/소문자를 구분하지 않는 시스템입니다. 메트릭 이름, 레이블 이름 또는 레이블 값과 같은 문자열은 문자열의 경우에만 다른 시계열과 다를 경우 동일한 시계열로 처리됩니다.
Note
이 동작은 대/소문자를 구분하는 시스템인 원시 오픈 소스 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 Managed Prometheus는 중복 시계열을 자동으로 삭제하지 않고 사용자에게 422 오류로 표시합니다. 이러한 오류가 발생하는 사용자는 시계열의 중복을 방지하기 위해 조치를 취해야 합니다.
예를 들어 사용자가 서로 다른 리소스 그룹에 저장된 두 개의 서로 다른 클러스터에 대해 동일한 "클러스터" 레이블 값을 사용하지만 동일한 AMW로 수집하는 경우 고유성을 위해 이러한 레이블 중 하나의 이름을 바꿔야 합니다. 이 오류는 이 시나리오의 두 클러스터에서 타임스탬프와 값이 동일한 에지 사례에서만 발생합니다.
이 문제는 고유 식별자 레이블을 추가하거나, 고유하도록 의도된 기존 레이블을 다시 계측하거나, relabel_configs를 사용하여 스크래핑 시점에 레이블을 삽입하거나 수정하여 해결할 수 있습니다.
자주 묻는 질문
이 섹션에서는 일반적인 질문에 대한 답변을 제공합니다.
메트릭의 전부 또는 일부가 누락되었습니다. 어떻게 해결할 수 있나요?
문제 해결 가이드를 사용하여 관리되는 에이전트에서 Prometheus 메트릭을 수집하는 방법을 알아봅니다.
이름은 같지만 대/소문자가 다른 두 개의 레이블이 있는 메트릭이 누락되는 이유는 무엇인가요?
Azure Managed Prometheus는 대/소문자를 구분하지 않는 시스템입니다. 메트릭 이름, 레이블 이름 또는 레이블 값과 같은 문자열은 문자열의 경우에만 다른 시계열과 다를 경우 동일한 시계열로 처리됩니다. 자세한 내용은 Prometheus 메트릭 개요를 참조하세요.
메트릭 데이터에 약간의 차이가 있습니다. 이 동작이 발생하는 이유는 무엇인가요?
노드 업데이트 중에 클러스터 수준 수집기에서 수집된 메트릭에 대한 메트릭 데이터의 간격이 1분에서 2분 간격으로 표시될 수 있습니다. 이 간격은 데이터가 실행되는 노드가 일반 업데이트 프로세스의 일부로 업데이트되기 때문에 발생합니다. 이 업데이트 프로세스는 kube-state-metrics 및 지정된 사용자 지정 애플리케이션 대상과 같은 클러스터 전체 대상에 영향을 미칩니다. 이 프로세스는 클러스터가 수동으로 업데이트되거나 자동 업데이트를 통해 업데이트되는 경우에 발생합니다.
이 동작은 예상되며 권장되는 경고 규칙에 영향을 주지 않습니다.