이 페이지에서는 Cloud Monitoring API에 Monitoring Query Language(MQL) 쿼리를 제공하는 방법을 설명합니다.
이 페이지에서는 MQL 쿼리 생성에 대해서는 다루지 않습니다. 예시 쿼리 집합은 예시를 참조하세요. MQL 참조는 언어에 대한 포괄적인 참조를 제공합니다.
MQL 기반 알림 정책에 대한 일반적인 정보는 MQL을 사용한 알림 정책을 참조하세요.
API에서 MQL 사용
Monitoring API의 다음 위치에서 MQL 쿼리를 제공할 수 있습니다.
MQL을 사용하여 시계열 데이터를 선택하고 조작하려면
timeSeries.query메서드를 호출합니다. 예시를 보려면timeSeries.query사용을 참조하세요.차트의 시계열 데이터를 선택하고 조작하려면
dashboards.create메서드를 호출할 때 쿼리를TimeSeriesQuery사양에 제공합니다. 예시를 보려면 차트 작성을 참조하세요.알림 정책에 MQL 기반 조건을 만들려면
alertPolicies.create를 호출할 때MonitoringQueryLanguageCondition조건을 가진 알림 정책의 조건을 설명합니다. 예를 들면 알림 정책 조건 만들기를 참조하세요.
timeSeries.query로 데이터 검색
MQL 쿼리로 API에서 시계열 데이터를 검색하려면 timeSeries.query 메서드를 사용합니다.
timeSeries.query 메서드는 JSON에서 다음과 같은 최소한의 구조를 사용합니다.
{
"query": string
}
query 필드 값에 다음 단순 쿼리에 표시된 대로 MQL의 문자열을 지정합니다.
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"
}
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h"
}
{
"query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m"
}
쿼리가 정렬되지 않은 출력 테이블을 생성할 때는 API를 직접 호출할 때 within 테이블 작업을 사용해서 기간을 제공해야 합니다. 측정항목 탐색기와 같은 차트 작성 도구는 기본 쿼리 기간을 제공합니다. 다음 JSON 스니펫의 쿼리는 측정항목 탐색기의 MQL 코드 편집기에서 작동하지만 API에 직접 제공된 경우 실패합니다.
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)"
}
이전 쿼리에 within 테이블 작업이 추가되어 이전 예시를 API에 직접 제공할 수 있습니다.
{
"query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h"
}
API를 실험하기 위해 timeSeries.query 참조 페이지에서 API 탐색기 도구를 사용할 수 있습니다.
API 탐색기 도구에 대한 소개는 API 탐색기를 참조하세요.
API를 시도하는 또 다른 방법은 쿼리를 텍스트 파일에 넣고 curl을 사용하여 쿼리를 실행하는 것입니다. 다음 예시에서는 query.json 파일의 쿼리를 timeSeries.query 메서드에 전달합니다.
curl -d @query.json -H "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" -X POST \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query
curl 사용에 대한 자세한 내용은 curl 호출을 참조하세요.
성공하면 쿼리는 요청된 시계열이 포함된 테이블을 반환합니다. 테이블은 두 가지 구성요소로 나뉩니다.
timeSeriesDescriptor는 테이블의 라벨 키, 라벨 값, 데이터 포인트를 설명합니다. 데이터는 포함되지 않으며, 단순히 데이터를 기술합니다.timeSeriesData에는 시계열 설명자에 설명된 데이터가 포함됩니다. 이 데이터는 쌍의 배열로 표시됩니다.- 쌍의 첫 번째 항목인
labelValues는 시계열 설명에 나열된 라벨의 값 집합을 기록합니다. - 두 번째
pointData는 지정된 라벨 값 집합으로 수집된 데이터를 나타내는 값/타임스탬프 쌍의 삽입된 배열입니다.
- 쌍의 첫 번째 항목인
응답은 형식이 약간 다시 지정되었으며 다음과 같습니다.
[{
"timeSeriesTable": {
"timeSeriesDescriptor": {
"labelDescriptors": [
{ "key": "resource.project_id" },
{ "key": "resource.zone" },
{ "key": "resource.instance_id" },
{ "key": "metric.instance_name" }
],
"valueDescriptors": [
{
"key": "value.utilization",
"valueType": "DOUBLE",
"metricKind": "GAUGE"
}
],
"pointDescriptors": [
{
"key": "value.utilization",
"valueType": "DOUBLE",
"metricKind": "GAUGE"
}
]
},
"timeSeriesData": [
{
"labelValues": [
{ "stringValue": "632526624816" },
{ "stringValue": "us-central1-a" },
{ "stringValue": "5106847938297466291" },
{ "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" }
],
"pointData": [
{
"values": [
{
"doubleValue": 0.063896992710942874
}
],
"timeInterval": {
"startTime": "1969-12-31T23:59:59.999999Z",
"endTime": "2020-03-02T20:17:00Z"
}
},
{ ... additional value/timestamp pairs ...}
]
},
{ ... additional labelValue/pointData pairs ...},
]
}
차트 작성하기
dashboards.create 메서드를 사용하여 대시보드 및 대시보드에 포함되는 차트를 프로그래매틱 방식으로 만들 수 있습니다.
MQL 기반 차트 생성과 다른 차트 생성의 유일한 차이점은 차트의 데이터 세트를 채우는 데 사용하는 TimeSeriesQuery 쿼리 유형입니다.
MQL 기반 차트 구성
MQL 쿼리의 경우 차트의 DataSet 배열에 있는 timeSeriesQueryLanguage 문자열 필드의 값으로 쿼리를 사용합니다.
다음은 MQL이 포함된 간단한 대시보드 정의입니다.
{
"displayName": "Dashboard for MQL chart (API)",
"gridLayout": {
"widgets": [
{
"title": "Min/Max Compute Engine CPU utilization",
"xyChart": {
"dataSets": [
{
"timeSeriesQuery": {
"timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union"
},
"plotType": "LINE",
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
},
"chartOptions": {
"mode": "COLOR"
}
}
}
]
}
}
이는 프로젝트에 'MQL용 대시보드(API)'라는 대시보드를 생성합니다. 대시보드에는 '최소/최대 Compute Engine CPU 사용률'이라는 차트가 포함되어 있습니다. 이 차트는 최댓값과 최솟값의 선 두 개를 보여줍니다.
이 예시 쿼리에 대한 자세한 내용은 union과 선택 항목 결합을 참조하세요.
차트 만들기
대시보드 JSON을 파일에 넣은 다음 gcloud beta monitoring dashboards create에 파일을 전달하거나 curl을 사용하여 https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards에 게시할 수 있습니다.
더 많은 예시를 보려면 대시보드 만들기를 참조하세요.
curl 사용에 대한 자세한 내용은 curl 호출을 참조하세요.
차트 및 대시보드 만들기에 대한 일반적인 정보는 API로 대시보드 관리하기를 참조하세요. 참조 자료는 Dashboards를 확인하세요.
알림 정책 조건 만들기
alertPolicies.create 메서드를 사용하여 프로그래매틱 방식으로 알림 정책을 만듭니다.
MQL 기반 알림 정책과 다른 알림 정책 생성의 유일한 차이점은 사용하는 Condition 유형입니다. 그렇지 않으면 다른 알림 정책과 마찬가지로 이 정책을 만듭니다.
다음은 Compute Engine CPU 사용률이 15퍼센트를 초과하는지 테스트하는 알림 정책 조건에 대한 간단한 MQL 쿼리를 보여줍니다.
fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'
MQL condition 알림 작업에 대한 자세한 내용은 MQL을 사용한 알림 정책을 참조하세요.
알림 정책 구성
MQL 쿼리를 기반으로 알림 정책을 빌드하려면 AlertPolicy 조건 유형 MonitoringQueryLanguageCondition을 사용합니다.
MonitoringQueryLanguageCondition의 구조는 다음과 같습니다.
{
"query": string,
"duration": string,
"trigger": {
object (Trigger)
}
}
query 필드의 값은 간결하거나 엄격한 양식의 MQL 알림 쿼리 문자열입니다. 이 문서의 예시는 간결한 양식입니다. 엄격한 양식에 대한 자세한 내용은 엄격한 양식 쿼리를 참조하세요.
duration 필드는 알림 정책이 트리거되기 전에 쿼리의 각 평가에서 true 값을 생성해야 하는 시간을 지정합니다. 자세한 내용은 측정항목 기반 알림 정책 동작을 참조하세요.
값은 초 단위로 표시되는 분입니다.(예: 10분 동안 600s사용)
trigger 필드는 duration 기간 동안 조건을 충족해야 하는 시계열 수를 개수 또는 백분율로 지정합니다. 기본값은 1개입니다. 자세한 내용은 Trigger를 참조하세요.
예제 알림 쿼리의 경우 길이가 10분이고 트리거 수가 1이면 구조가 다음과 같이 표시됩니다.
{
"query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
"duration": "600s",
"trigger" : {
"count": 1
}
}
이 구조를 알림 정책 구조에 삽입되는 조건의 conditionMonitoringQueryLanguage 필드 값으로 사용합니다.
이러한 구조에 대한 자세한 내용은 AlertPolicy를 참조하세요.
다음은 JSON 형식의 MonitoringQueryLanguageCondition 조건이 포함된 완전한 최소 정책을 보여줍니다.
{
"displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)",
"combiner":"OR",
"conditions":[
{
"displayName":"MQL-based utilization condition, API",
"conditionMonitoringQueryLanguage":
{
"query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
"duration": "600s",
"trigger" : {
"count": 1
},
},
}
],
}
알림 정책 만들기
정책을 만들려면 알림 정책 JSON을 파일에 넣은 다음 파일을 gcloud alpha monitoring policies create에 전달하거나 curl를 사용하여 https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies에 게시합니다.
알림 정책에 대한 Monitoring API에 대한 자세한 내용은 API를 통한 알림 정책 관리를 참조하세요.
curl 사용에 대한 자세한 내용은 curl 호출을 참조하세요.
curl 호출
각 curl 호출에는 인수 집합과 API 리소스의 URL이 포함됩니다. 일반적인 인수에는 Google Cloud 프로젝트 ID와 인증 토큰이 포함됩니다. 이 값은 여기에서 PROJECT_ID 및 TOKEN 환경 변수로 표시됩니다.
HTTP 요청의 유형을 지정하기 위해 다른 인수를 지정해야 할 수도 있습니다(예: -X DELETE). 기본 요청은 GET이므로 예시에서는 이를 지정하지 않습니다.
각 curl 호출은 다음과 같은 일반적인 구조를 취합니다.
curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>
curl을 사용하려면 프로젝트 ID와 액세스 토큰을 지정해야 합니다. 입력 및 오류를 줄이려면 이를 환경 변수에 입력하여 curl에 전달하면 됩니다.
이러한 변수를 설정하려면 다음 안내를 따르세요.
측정항목 범위의 범위 지정 프로젝트의 ID를 저장할 환경 변수를 만듭니다. 다음 단계는 변수
PROJECT_ID를 호출합니다.PROJECT_ID=a-sample-projectGoogle Cloud CLI에 인증합니다.
gcloud auth login선택사항. 각
gcloud명령어로 프로젝트 ID를 지정하지 않으려면 gcloud CLI를 사용하여 프로젝트 ID를 기본값으로 설정합니다.gcloud config set project ${PROJECT_ID}승인 토큰을 만들고 환경 변수에 저장합니다. 다음 단계는 변수
TOKEN을 호출합니다.TOKEN=`gcloud auth print-access-token`정기적으로 액세스 토큰을 새로고침해야 합니다. 작업한 명령어에서 사용자가 인증되지 않았다고 갑자기 보고하면 이 명령어를 다시 실행합니다.
액세스 토큰을 받았는지 확인하려면
TOKEN변수를 출력합니다.echo ${TOKEN} ya29.GluiBj8o....