MQL 언어 정보

이 페이지에서는 다음 주제를 포함하여 Monitoring 쿼리 언어 (MQL)에 대한 일반적인 정보를 제공합니다.

• 테이블 작업 및 함수에 대한 쿼리 단축키
• MQL fetch 작업의 변형
• 엄격한 형식 쿼리
• resource.project_id 열 일치에 대한 규칙
• '에지 효과'가 측정항목 유형에서 계산된 비율에 미치는 영향
• MQL에서 지원되는 날짜 형식
• 쿼리 길이 및 복잡성에 대한 제한.
• MQL의 매크로

이 정보는 MQL을 Google Cloud Console에서 사용하든 Cloud Monitoring API에서 사용하든 관계없이 적용됩니다. MQL 쿼리 구조에 대한 자세한 내용은 예시를 참조하세요.

테이블 작업 및 함수 단축키

쿼리는 일반적으로 파이프 (|)로 연결된 테이블 작업의 연결 체인으로 구성되며, 각각은 테이블 작업 이름으로 시작되고 표현식 목록으로 이어집니다. 표현식에는 모든 인수를 명시적으로 나열하는 함수 호출이 포함될 수 있습니다. 하지만 모니터링 쿼리 언어를 사용하면 여러 단축키를 사용해 쿼리를 표현할 수 있습니다.

이 섹션에서는 함수를 테이블 작업으로 사용하고 값 열의 바로가기를 함수에 대한 인수로 사용하는 단축키를 설명합니다.

전체 목록은 테이블 작업 단축키를 참조하세요.

테이블 작업 단축키

fetch, group_by, filter 작업을 사용하는 경우 인수가 의도한 작업을 결정하기에 충분할 때 명시적 테이블 작업을 생략할 수 있습니다. 예를 들면 다음 쿼리와 같습니다.

gce_instance::compute.googleapis.com/instance/cpu/utilization

이 값은 다음과 동일합니다.

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization

다음 group_by 작업은 동일합니다.

         [zone], mean(val())
group_by [zone], mean(val())

필터 테스트를 괄호로 묶는 경우 filter라는 단어를 생략할 수 있습니다. 예를 들어 다음 두 filter 작업은 동일합니다.

       (instance_name =~ 'apache.*')
filter instance_name =~ 'apache.*'

이러한 단축키 양식을 쿼리에서 결합할 수 있습니다. 예를 들면 다음 쿼리와 같습니다.

gce_instance::compute.googleapis.com/instance/cpu/utilization
| (instance_name =~ 'apache.*')
|  [zone], mean(val())

다음의 좀 더 명시적인 형태와 동일합니다.

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| filter instance_name =~ 'apache.*'
| group_by [zone], mean(val())

테이블 작업 단축키에 대한 자세한 내용은 MQL 참조의 테이블 작업 바로가기를 참조하세요.

함수를 테이블 작업으로 사용

테이블 작업은 일반적으로 테이블 작업 이름으로 시작합니다. 하지만 MQL을 사용하면 테이블 작업을 함수 이름으로 대신 시작할 수 있습니다.

명명된 함수가 입력 테이블의 값 열에 대한 변환을 수행할 때 함수 이름을 사용할 수 있습니다. 이 교체는 이름이 지정된 함수의 종류에 따라 group_by, align 또는 value 테이블 작업의 바로가기입니다.

일반적인 형식은 다음과 같습니다.

|  FUNCTION_NAME ARG, ARG ... 

테이블 작업에서 함수는 입력 테이블의 값 열을 인수로 사용하고, 인수 뒤에는 함수 자체에 대한 모든 인수가 뒤따릅니다. 함수를 테이블 작업으로 사용하는 경우 일반적으로 주변 괄호 (())를 함수와 함께 사용하는 대신 테이블 작업 형식에 쉼표로 구분된 목록으로 인수를 지정합니다.

단축키를 확장하여 생성된 전체 테이블 작업은 함수의 종류에 따라 다릅니다.

• group_by: 모든 시계열 식별자 열을 집계하는 group_by 작업으로 집계 함수를 사용하는 경우 (즉, 그룹화를 위해 []을 사용하는 경우) 함수를 단축키로 사용할 수 있습니다. 예를 들면 다음과 같습니다.

  | distribution powers_of(1.1)

  단축키입니다.

  | group_by [], distribution(val(0), powers_of(1.1))

• align: 정렬 함수를 align 작업의 인수로 사용하는 경우 함수를 단축키로 사용합니다. 예를 들면 다음과 같습니다.

  | delta

  단축키입니다.

  | align delta()

  마찬가지로,

  | rate 10m

  단축키입니다.

  | align rate(10m)

  정렬기 함수는 입력 시계열을 암시적 인수로 사용하므로 여기에 값 열이 명시적으로 제공되지 않습니다.

• value: 다른 모든 함수는 value 테이블 작업의 바로가기 역할을 할 수 있습니다. 예를 들면 다음과 같습니다.

  | mul 3.3

  단축키입니다.

  | value mul(val(0), 3.3)

  마찬가지로,

  | div

  단축키입니다.

  | value div(val(0), val(1))

  div는 입력 테이블 연산을 두 개의 값 열로 단축하고 비율인 값 열이 하나 있는 테이블 작업을 생성합니다.

값 열 함수 단축키

입력에 단일 값 열이 있으면 .function를 function(val())의 바로가기로 사용하고, 두 값이 있을 경우 function(val(0), val(1))의 바로가기로 사용할 수 있습니다.

선행 점은 '다음 함수를 호출하여 입력 지점 값 열(또는 열)을 함수의 인수로 제공합니다'라는 의미입니다.

예를 들어 .mean는 mean(val())의 단축키입니다. 다음은 동일합니다.

group_by [zone], .mean
group_by [zone], mean(val())

입력 테이블에 값 열이 여러 개인 경우 각 열은 이 단축키의 함수에 대한 인수가 됩니다. 예를 들어 입력 테이블에 두 개의 값 열이 있으면

.div

단축키입니다.

div(val(0), val(1))

이 단축키를 사용하면 값 열을 참조하지 않는 인수를 제공할 수 있습니다. 추가 인수는 값 열 인수 뒤에 제공됩니다. 예를 들어 입력 테이블에 값 열이 한 개 있다면,

.div(3)

는 다음과 동일합니다.

div(val(0), 3)

fetch 변형

fetch 작업은 일반적으로 모니터링 리소스 및 측정항목 유형의 쌍으로 이름이 지정된 시계열 테이블을 반환합니다. 예를 들면 다음과 같습니다.

fetch gce_instance :: compute.googleapis.com/instance/cpu/utilization

측정항목이 모니터링 리소스 유형 하나에만 적용되는 경우 쿼리에서 모니터링 리소스를 생략할 수 있습니다. 다음 쿼리는 CPU 사용량 측정항목이 gce_instance 모니터링 리소스에만 적용되기 때문에 이전 쿼리와 동일합니다.

fetch compute.googleapis.com/instance/cpu/utilization

fetch 작업은 후속 metric 작업에서 지정된 측정항목을 사용하여 모니터링 리소스 유형만 지정할 수 있습니다. 예를 들어 이 예시는 이전의 fetch 예시와 같습니다.

fetch gce_instance
| metric metric compute.googleapis.com/instance/cpu/utilization

이 방법으로 fetch를 분할하면 동일한 모니터링 리소스에 대해 2개의 서로 다른 측정항목을 가져올 때 유용할 수 있습니다. 예를 들어 다음 쿼리는 소비된 CPU 초당 사용된 패킷 수를 계산합니다.

fetch gce_instance
| {
    metric compute.googleapis.com/instance/network/received_packets_count ;
    metric compute.googleapis.com/instance/cpu/usage_time
  }
| ratio

fetch를 분할하면 모니터링되는 리소스의 라벨에만 필터링을 적용할 수도 있습니다.

fetch gce_instance
| filter resource.zone =~ "asia.*"
| {
    metric compute.googleapis.com/instance/network/received_packets_count ;
    metric compute.googleapis.com/instance/cpu/usage_time
  }
| ratio

모니터링 리소스 유형의 이름만 지정하는 fetch은 그 뒤에 metric 작업이 이어지고, filter 작업이 개입될 수 있습니다.

엄격한 형식 쿼리

엄격한 쿼리는 간결한 쿼리에 사용된 바로가기나 암시적 값이 없는 쿼리입니다. 엄격한 쿼리의 특징은 다음과 같습니다.

• 모든 단축키가 대체됩니다.
• 모든 암시적 인수는 명시적입니다.
• 열은 전체 이름으로 참조됩니다.
• 새 열에 명시적으로 지정된 이름입니다.
• 암시적으로 제공되는 정렬 작업은 명시적으로 지정됩니다.

엄격한 형식을 사용하면 쿼리가 입력 테이블 구조의 변화에 더욱 탄력적으로 대응하며 쿼리가 수행하는 작업을 더 명확하게 수행할 수 있습니다. 쿼리를 엄격한 방식으로 입력한다고 해서 쿼리가 더 효율적으로 실행되는 것은 아닙니다.

차트에 대한 쿼리를 저장하면 엄격한 형식으로 변환됩니다. 저장 작업의 확인 대화상자에 엄격한 형식이 표시됩니다.

알림 정책에 대한 간결한 쿼리는 엄격한 형식으로 변환되지 않습니다. 알림 정책의 쿼리는 쿼리가 제공될 때 저장됩니다. 간결한 형식 또는 엄격한 형식 중 하나를 사용할 수 있습니다.

단축키와 엄격한 형식을 모두 사용할 수 있기 때문에 서로 매우 다르게 보이는 동일한 MQL 쿼리가 나타날 수 있습니다. 예를 들어 다음 쿼리는 소비된 CPU 초당 수신된 패킷 수를 계산하며 다음 단축키를 사용합니다.

gce_instance
| (zone =~ ".*-a")
| {
    compute.googleapis.com/instance/network/received_packets_count ;
    compute.googleapis.com/instance/cpu/usage_time
  }
| join
| div

이 쿼리를 차트 또는 알림 정책의 일부로 저장하면 엄격한 형식 쿼리도 똑같은 작업을 수행합니다. 그러나 다음 예와 같이 엄격한 형식은 매우 다를 수 있습니다.

fetch gce_instance
| filter (resource.zone =~ '.*-a')
| { t_0:
      metric 'compute.googleapis.com/instance/network/received_packets_count'
      | align delta() ;
    t_1:
      metric 'compute.googleapis.com/instance/cpu/usage_time'
      | align delta() }
| join
| value [v_0: div(t_0.value.received_packets_count, t_1.value.usage_time)]

차트의 저장된 정의를 수정하면 코드 편집기에 엄격한 형식이 표시됩니다.

resource.project_id 열 일치

Google Cloud 프로젝트에는 메뉴에는 표시되지만 프로젝트를 고유하게 식별하지는 않는 표시 이름이 있습니다. 프로젝트 표시 이름은 'Monitoring 데모'일 수 있습니다.

또한 프로젝트에는 식별자 역할을 하는 두 필드가 있습니다.

• 프로젝트 ID: 고유한 문자열 식별자입니다. 이는 표시 이름을 기반으로 하는 경우가 많습니다. 프로젝트 ID는 프로젝트가 생성될 때 설정되며, 일반적으로 고유성을 위해 프로젝트 이름의 요소를 연결하고 끝에 숫자를 추가할 수 있습니다. 프로젝트 ID의 형식은 'monitoring-demo' 또는 'monitoring-demo-2349"일 수 있습니다. 프로젝트 ID를 흔히 프로젝트 이름이라고 부르는 경우도 있습니다.
• 프로젝트 번호: 고유한 숫자 식별자입니다.

모든 모니터링 리소스 유형에는 project_id 라벨이 포함되며, 리소스를 소유한 포로젝트의 프로젝트 번호와 해당 리소스에 대한 데이터를 문자열로 표시됩니다.

MQL 쿼리에서 이 라벨을 resource.project_id로 참조합니다. resource.project_id 라벨은 텍스트 형식의 프로젝트 번호를 값으로 갖지만, MQL은 특정 상황에서 그 값을 프로젝트 ID로 변환합니다.

다음 경우에 MQL은 resource.project_id 라벨 값을 프로젝트 번호 대신 프로젝트 ID로 취급합니다.

• 차트의 범례에는 resource.project_id 라벨 값의 프로젝트 번호 대신 프로젝트 ID가 표시됩니다.

• 문자열 리터럴에 대해 resource.project_id 값을 동등 비교하면 프로젝트 번호와 프로젝트 ID를 모두 인식합니다. 예를 들어 다음 두 프로젝트는 모두 이 프로젝트에서 소유한 리소스에 대해 참(true)를 반환합니다.

  • resource.project_id == "monitoring-demo"
  • resource.project_id == "530310927541"

  이 경우 == 및 != 연산자와 함수 양식 eq() 및 ne()에 적용됩니다.

• resource.project_id 라벨의 정규 표현식 일치는 프로젝트 번호 또는 프로젝트 ID에 대해 제대로 작동합니다. 예를 들어 다음 두 표현식 모두 이 프로젝트에서 소유한 리소스에 대해 true를 반환합니다.

  • resource.project_id =~ "monitoring-.*"
  • resource.project_id =~ ".*27541"

  이 경우 =~ 및 !~ 연산자와 함수 형식 re_full_match에 적용됩니다.

다른 모든 경우에는 resource.project_id 라벨의 실제 값이 사용됩니다. 예를 들어 concatenate("project-", resource.project_id)는 project-monitoring-demo가 아니라 project-530310927541 값을 생성합니다.

비율과 '에지 효과'

일반적으로 라벨 값을 사용하여 단일 측정항목 유형에 대해 수집된 시계열을 기준으로 비율을 계산하는 것이 가장 좋습니다. 서로 다른 두 측정항목 유형에서 계산되는 비율에는 샘플링 기간 및 정렬 기간의 차이로 인한 문제점이 나타날 수 있습니다.

예를 들어 두 가지 측정항목 유형, RPC 총 개수와 RPC 오류 개수가 있고 총 RPC에 대한 오류 개수 RPC의 비율을 계산한다고 가정해 보겠습니다. 실패한 RPC는 두 측정항목 유형 모두의 시계열에 포함됩니다. 따라서 시계열을 정렬할 때 두 시계열 모두 동일한 정렬 간격으로 실패한 RPC가 표시되지 않을 수 있습니다. 이러한 차이는 다음과 같은 여러 이유로 발생할 수 있습니다.

• 동일한 이벤트를 기록하는 서로 다른 시계열이 두 개 있으므로 컬렉션을 구현하는 두 가지 기본 카운터 값이 있게 되고 원자적으로 업데이트되지 않습니다.
• 샘플링 레이트는 다를 수 있습니다. 시계열이 공통 기간으로 정렬되면 단일 이벤트에 대한 이벤트 수가 서로 다른 측정항목의 시계열에 가까운 정렬 간격으로 표시될 수 있습니다.

해당 정렬 간격의 값 수에 차이가 있으면 1/0 또는 2/1과 같은 무의미한 error/total 비율 값이 발생할 수 있습니다.

비율에 사용되는 숫자가 클수록 무의미한 값이 나올 가능성이 낮습니다. 샘플링 기간보다 긴 정렬 기간을 사용하거나 특정 라벨의 데이터를 그룹화하여 집계하면 더 큰 숫자를 사용할 수 있습니다. 이러한 기법은 특정 간격의 포인트 수에 미치는 작은 차이의 영향을 최소화합니다. 즉, 간격의 예상 포인트 수가 300인 경우보다 3일 경우 2점 차이가 더 중요합니다.

기본 제공 측정항목 유형을 사용하는 경우 필요한 값을 얻기 위해 측정항목 유형 전반에서 비율을 계산해야 할 수도 있습니다.

두 개의 서로 다른 측정항목에서 RPC에서 오류 상태를 반환하는 RPC와 같이 같은 항목을 계산할 수 있는 커스텀 측정항목을 설계하는 경우 각 측정항목이 한 번만 포함된 단일 측정항목을 사용하는 것이 좋습니다. 예를 들어 RPC를 계산 중이고 모든 RPC에 대한 실패한 RPC 비율을 추적한다고 가정해보세요. 이 문제를 해결하려면 RPC를 계산하도록 단일 측정항목 유형을 만들고 라벨을 사용해서 'OK' 상태를 포함해서 호출 상태를 기록합니다. 그런 다음 각 상태 값 오류 또는 'OK'가 해당 사례에 대한 단일 카운터를 업데이트하여 기록됩니다.

MQL 날짜 형식

MQL는 현재 제한된 수의 날짜 형식을 지원합니다. MQL 쿼리에서 날짜는 다음 중 하나로 표현됩니다.

• d'BASE_STRING'
• D'BASE_STRING'

BASE_STRING은 2010/06/23-19:32:15-07:00 형식의 문자열입니다. 첫 번째 대시 (-)는 날짜와 시간을 분리하여 공백으로 바꿀 수 있습니다. 시간 구성요소에서는 시계 시간(19:32:15) 또는 시간대 지정자 (-07:00)의 일부를 삭제할 수 있습니다.

다음 예시는 MQL 쿼리의 유효한 날짜입니다.

• d'2010/06/23-19:32:15-07:00'
• d'2010/06/23 19:32:15-07:00'
• d'2010/06/23 19:32:15'
• D'2010/06/23 19:32'
• d'2010/06/23-19'
• D'2010/06/23 -07:00'

다음 테이블은 BASE_STRING의 문법을 보여줍니다.

구조	의미
%Y/%m/%d	날짜
%Y/%m/%d %H %Y/%m/%d-%H	날짜, 시
%Y/%m/%d %H:%M %Y/%m/%d-%H:%M	날짜, 시, 분
%Y/%m/%d %H:%M:%S %Y/%m/%d-%H:%M:%S	날짜, 시간, 분, 초
%Y/%m/%d %H:%M:%E*S %Y/%m/%d-%H:%M:%E*S	날짜, 시간, 분, 소수점 이하 초
%Y/%m/%d %Ez	시간대 포함 날짜
%Y/%m/%d %H%Ez %Y/%m/%d-%H%Ez	날짜, 시간, 시간대 포함
%Y/%m/%d %H:%M%Ez %Y/%m/%d-%H:%M%Ez	날짜, 시간, 분, 시간대 포함
%Y/%m/%d %H:%M:%S%Ez %Y/%m/%d-%H:%M:%S%Ez	날짜, 시간, 분, 초, 시간대 포함
%Y/%m/%d %H:%M:%E*S%Ez %Y/%m/%d-%H:%M:%E*S%Ez	날짜, 시간, 분, 소수점 이하 초, 시간대 포함

쿼리의 길이와 복잡성

Monitoring Query Language는 제한없이 길고 복잡할 수 있습니다.

• UTF-8로 인코딩된 쿼리 텍스트는 10,000바이트로 제한됩니다.
• 쿼리는 2,000개 언어 구성으로 제한됩니다. 즉, AST^† 복잡성이 2,000개 노드로 제한됩니다.

^† 추상 구문 트리 또는 AST는 소스 코드 표현입니다. 여기서 MQL 쿼리 문자열은 트리 내의 노드가 코드의 구문 구조에 매핑됩니다.

MQL 매크로

미리보기

이 제품 또는 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 제품 및 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

MQL에는 매크로 정의 유틸리티가 포함되어 있습니다. MQL 매크로를 사용하여 반복 작업을 대체하고, 복잡한 쿼리의 가독성을 높이고, 더 쉽게 쿼리를 개발할 수 있습니다. 테이블 작업 및 함수에 대한 매크로를 정의할 수 있습니다.

매크로 정의는 def 키워드로 시작합니다.

쿼리를 엄격한 형식으로 변환하면 매크로 호출이 해당하는 텍스트로 대체되고 매크로 정의가 삭제됩니다.

매크로가 포함된 차트 쿼리를 저장하면 쿼리가 엄격한 형식으로 변환되므로 매크로가 보존되지 않습니다. 알림 정책의 조건에 대한 쿼리를 저장하면 쿼리가 엄격한 형식으로 변환되지 않으므로 매크로가 보존됩니다.

테이블 작업 매크로

매크로를 작성하여 새 테이블 작업을 수행할 수 있습니다. 일반 구문은 다음과 같습니다.

def MACRO_NAME [MACRO_PARAMETER[, MACRO_PARAMETER]] = MACRO_BODY ;

매크로를 호출하려면 다음 구문을 사용합니다.

@MACRO_NAME [MACRO_ARG [, MACRO_ARG]]

예를 들어 다음 쿼리를 사용하여 CPU 사용률 데이터를 가져온다고 가정해 보겠습니다.

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| every 1m
| group_by [zone], mean(val())

첫 번째 줄은 다음 매크로로 바꿀 수 있습니다.

def my_fetch = fetch gce_instance::compute.googleapis.com/instance/cpu/utilization ;

쿼리에서 매크로를 호출하려면 원래 fetch를 다음과 같이 바꿉니다.

def my_fetch = fetch gce_instance::compute.googleapis.com/instance/cpu/utilization ;

@my_fetch
| every 1m
| group_by [zone], mean(val())

두 번째 줄과 세 번째 줄을 인수를 사용하는 매크로로 바꿀 수 있습니다. 매크로 정의에는 매크로의 매개변수가 나열되고 매크로 본문에서 매크로의 매개변수는 $MACRO_PARAMETER로 표시됩니다. 예를 들어 다음 매크로를 정의할 수 있습니다.

def my_every time_arg = every $time_arg ;

def my_group label, aggr = group_by [$label], $aggr ;

이러한 매크로를 호출하고 인수를 제공하려면 매크로 호출에서 쉼표로 구분된 목록에 인수를 지정합니다. 다음은 정의된 모든 매크로 및 해당 호출이 있는 쿼리를 보여줍니다.

def my_fetch = fetch gce_instance::compute.googleapis.com/instance/cpu/utilization ;
def my_every time_arg = every $time_arg ;
def my_group label, aggr = group_by [$label], $aggr ;

{@my_fetch}
| @my_every 1m
| @my_group zone, mean(val())

쿼리가 엄격한 형식으로 변환되면 매크로가 보존되지 않습니다. 예를 들어 이전 쿼리의 엄격한 형식은 다음과 같습니다.

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| align mean_aligner()
| every 1m
| group_by [resource.zone],
           [value_utilization_mean: mean(value.utilization)]

함수 매크로

MQL 함수의 경우 괄호 안에 쉼표로 구분된 목록에 매개 변수를 지정합니다. 괄호는 함수 매크로를 테이블 작업 매크로와 구분합니다. 인수가 없는 경우에도 호출에 괄호가 표시되어야 합니다. 쿼리가 엄격한 형식으로 변환되면 매크로가 보존되지 않습니다.

def MACRO_NAME([MACRO_PARAMETER [, MACRO_PARAMETER]]) = MACRO_BODY ;

예를 들어 다음 쿼리는 두 개의 측정항목으로 테이블을 검색하고 두 테이블을 두 개의 값 열로 구성된 테이블로 결합하며 received_percent라는 열의 총 바이트 대비 수신된 바이트 비율을 계산합니다.

{
  fetch k8s_pod :: kubernetes.io/pod/network/received_bytes_count ;
  fetch k8s_pod :: kubernetes.io/pod/network/sent_bytes_count
}
| join
| value [received_percent: val(0) * 100 / (val(0) + val(1))]

received_percent 계산을 다음 예시와 같은 매크로로 바꿀 수 있습니다.

def recd_percent(recd, sent) = $recd * 100 / ($recd + $sent) ;

함수 매크로를 호출하려면 다음 구문을 사용합니다.

@MACRO_NAME([MACRO_ARG[, MACRO_ARG]])

인수 없이 함수 매크로를 호출할 때는 테이블 작업 매크로 호출과 구분을 위해 빈 괄호를 지정해야 합니다.

다음 예시는 비율 계산 매크로가 포함된 이전 쿼리를 보여줍니다.

def recd_percent(recd, sent) = $recd * 100 / ($recd + $sent) ;

{
  fetch k8s_pod :: kubernetes.io/pod/network/received_bytes_count ;
  fetch k8s_pod :: kubernetes.io/pod/network/sent_bytes_count
}
| join
| value [received_percent: @recd_percent(val(0), val(1))]

매크로 기능

MQL 매크로는 C 전처리기에서 사용되는 매크로와 같은 텍스트 요소가 아닌 구문 요소입니다. 즉, MQL 매크로 본문은 항상 구문적으로 유효한 표현식이어야 합니다. 이는 의미론적으로 유효하지 않을 수 있으며 매크로 인수와 매크로가 확장된 위치에 따라서도 달라집니다.

MQL 매크로는 구문적이므로 확장할 수 있는 표현식 종류에 거의 제한이 없습니다. 구문 매크로는 추상 구문 트리를 조작하기 위한 또 다른 방법입니다. 다음 예시에서는 구문 매크로를 사용하여 수행할 수 있는 여러 작업을 보여줍니다.

# Abbreviating a column name.
def my_col() = instance_name;

# Map-valued macro.
def my_map(c) = [$c, @my_col()];

# Abbreviating a string.
def my_zone() = 'us-central.*';

# Abbreviating a filter expression.
def my_filter(f) = zone =~ @my_zone() && $f;

또한 MQL은 암시적 문자열 리터럴 연결을 지원합니다. 이 기능은 긴 측정항목 이름이 포함된 쿼리를 작성할 때 매우 유용할 수 있습니다. 문자열 리터럴, 그리고 문자열 리터럴이 되어야 하는 매크로 인수가 매크로 본문에서 나란히 표시되면 매크로 확장은 이를 단일 문자열 리터럴로 연결합니다.

다음 예시에서 gce_instance는 BARE_NAME 어휘 요소입니다. 이는 테이블 이름을 빌드하는 데 유용한 문자열 리터럴로 자동 승격됩니다.

# Builds a table name in domain 'd' with the suffix 'm'.
def my_table(d, m) = gce_instance::$d '/instance/' $m;

# Table name under the given domain.
def my_compute_table(m) = @my_table('compute.googleapis.com', $m);

모두 종합하면 다음 쿼리는 이전에 정의된 모든 매크로를 사용합니다.

fetch @my_compute_table('cpu/utilization')
| filter @my_filter(instance_name =~ 'gke.*')
| group_by @my_map(zone)

매크로 인수는 구문상 올바른 경우 임의의 표현식일 수도 있습니다. 예를 들어 my_filter 매크로는 instance_name =~ 'gke.*'와 같은 부울 표현식을 첫 번째 인수로 사용할 수 있습니다.

다음 쿼리는 다음과 같이 테이블 작업을 축약하는 데에도 매우 유용할 수 있습니다.

# Calculate the ratio between compute metrics 'm1' and 'm2'.
def my_compute_ratio m1, m2 =
  { fetch @my_compute_table($m1); fetch @my_compute_table($m2) }
  | join | div;

# Use the table op macro to calculate the ratio between CPU utilization and
# the number of reserved cores per zone.
@my_compute_ratio 'cpu/utilization', 'cpu/reserved_cores' | group_by [zone]

마지막으로 함수 매크로는 일반 함수처럼 작동할 수 있습니다. 즉, 입력 테이블의 값 열이 매크로의 첫 번째 인수가 되는 함수 승격을 허용합니다. 다음 예시는 함수 매크로를 사용하는 이전 쿼리의 변형을 보여줍니다.

# Simple arithmetic macro.
def my_add_two(x) = $x + 2;

# Similar to previous query, but now using the new arithmetic macro with
# function argument promotion.
fetch @my_compute_table('cpu/utilization')
| filter @my_filter(instance_name =~ 'gke.*')
| group_by @my_map(zone), [.sum.@my_add_two]

제한사항

MQL 매크로 기능은 다음을 지원하지 않습니다.

• 매크로 정의 중첩: 다른 매크로에 있는 본문의 매크로를 정의할 수 없습니다.
• 재귀적으로 정의된 매크로. 매크로 본문에서 매크로 자신을 비롯해 완전히 정의되지 않은 모든 매크로를 참조할 수 없습니다.
• 매크로 정의 함수를 테이블 작업으로 사용
• 매크로 인수를 함수 또는 테이블 작업의 이름으로 사용
• 쿼리가 엄격한 형식으로 변환될 때 매크로 보존 매크로 호출은 해당 표현식으로 대체되고 매크로 정의는 삭제됩니다.