MQL용 코드 편집기 사용

이 섹션에서는 모니터링 쿼리 언어(MQL)용 코드 편집기 기능을 설명합니다. 이 편집기는 Google Cloud 콘솔에서 사용할 수 있으며, 유효한 MQL 쿼리를 만들기 위한 추천, 오류 감지, 기타 지원을 제공합니다.

이 페이지에서는 MQL 언어를 다루지 않습니다. 예시 집합과 언어에 대한 자세한 내용은 예시 및 MQL 언어 정보를 참조하세요. MQL 참조는 언어에 대한 포괄적인 참조를 제공합니다.

코드 편집기에 액세스

측정항목 탐색기를 사용할 때 코드 편집기에 액세스하려면 다음을 수행합니다.

1. Google Cloud 콘솔에서  측정항목 탐색기 페이지로 이동합니다.

   측정항목 탐색기로 이동

   검색창을 사용하여 이 페이지를 찾은 경우 부제목이 Monitoring인 결과를 선택합니다.

2. 쿼리 빌더 창의 툴바에서 이름이  MQL 또는  PromQL인 버튼을 선택합니다.
3. 언어 전환 버튼에 MQL이 선택되어 있는지 확인합니다. 언어 전환 버튼은 쿼리 형식을 지정할 수 있는 동일한 툴바에 있습니다.

대시보드에 차트를 만들 때 비슷한 단계를 수행하여 코드 편집기에 액세스합니다.

코드 편집기 사용

코드 편집기를 사용하려면 쿼리 편집기에 쿼리를 입력하고 쿼리 실행을 클릭합니다.

자동 완성

쿼리를 입력하면 편집기에서 구문적으로 유효한 완료 목록을 표시합니다. Control+Space를 눌러 자동 완성 메뉴를 수동으로 표시하고 Escape를 눌러 닫을 수 있습니다.

옵션 목록을 탐색하려면 화살표 키를 사용하세요. Enter를 누르면 선택한 항목이 삽입됩니다.

사용 가능한 모든 선택 항목에 공통적인 프리픽스를 삽입하려면 Tab를 누릅니다.

오류 메시지

오류 메시지는 편집기 창 하단에 표시됩니다.

쿼리에 자동 완성 제안을 방해하는 오류가 있는 경우 입력하는 동안 오류 메시지가 표시됩니다. 그렇지 않으면 쿼리를 실행할 때 오류 메시지가 표시됩니다.

코드 폴딩

편집기에서 쿼리 세그먼트를 접을 수 있는 코드 폴딩을 제공하므로 일시적으로 보기에서 숨길 수 있습니다.

편집기는 다음 스크린샷과 같이 행 번호 옆의 캐럿을 포함한 쿼리의 폴더블 세그먼트를 나타냅니다.

찾기 및 바꾸기

편집기는 찾기 및 바꾸기 기능을 지원합니다. 쿼리에서 검색어를 찾고 필요한 경우 바꾸려면 Control+F(Mac의 경우 Command+F)를 누릅니다. 다음 스크린샷은 기능을 보여줍니다.

편집기 제어

편집기에는 쿼리와 상호작용하는 방식을 결정하는 두 가지 제어가 있습니다.

기본적으로 쿼리는 쿼리 실행을 클릭할 때만 실행됩니다. 쿼리를 입력하면 쿼리가 자동으로 실행되도록 코드 편집기를 설정할 수 있지만 이 옵션은 기본적으로 중지되어 있습니다.

자동 실행 옵션을 사용 설정하려면 자동 실행 전환을 사용합니다. 이 옵션을 사용하면 편집기가 다음과 같이 작동합니다.

• 쿼리 실행 버튼이 표시되지 않습니다.
• 입력하는 동안 오류 메시지가 계속 표시됩니다.

• 불완전하지만 오류가 없는 쿼리의 끝에 커서가 있으면 편집기가 제어 막대에 노란색 삼각형을 표시합니다. 공간이 있으면 불완전한 쿼리 텍스트도 표시됩니다.

  코드 편집기는 불완전한 쿼리를 평가하지 않습니다.

또한 코드 편집기와 차트 리전 사이에 그랩 막대가 있습니다. 이 막대를 사용하여 두 리전의 상대적 크기를 변경할 수 있습니다.

차트 저장

측정 항목 탐색기 사용

측정 항목 탐색기의 코드 편집기에는 차트를 대시보드에 저장하는 옵션이 있습니다. 차트를 저장하려면 다음을 수행합니다.

1. 자동 실행 옵션을 사용 설정하지 않은 경우 차트를 저장하기 전에 쿼리 실행을 클릭하여 쿼리를 실행합니다. 쿼리를 먼저 실행하지 않으면 코드 편집기가 마지막으로 실행된 쿼리를 저장합니다.

2. 차트 저장을 클릭합니다. 차트를 저장하면 쿼리가 엄격한 양식으로 교체된다는 것을 알리는 대화상자가 표시됩니다. 자세한 내용은 엄격한 형식 쿼리를 참조하세요.

3. 차트 저장을 계속하려면 다음 안내를 따르세요.

   1. 차트에 자세한 제목을 지정합니다.
   2. 새 차트에 사용할 대시보드를 선택합니다.
   3. 대화상자에서 저장을 클릭합니다.

대시보드 사용

대시보드에 추가하려는 차트를 저장하려면 다음을 수행합니다.

1. 차트에 자세한 제목을 지정합니다.

2. 자동 실행 옵션을 사용 설정하지 않은 경우 차트를 저장하기 전에 쿼리 실행을 클릭하여 쿼리를 실행합니다. 쿼리를 먼저 실행하지 않으면 코드 편집기가 마지막으로 실행된 쿼리를 저장합니다.

3. 저장을 클릭합니다. 차트를 저장하면 쿼리가 엄격한 양식으로 교체된다는 것을 알리는 대화상자가 표시됩니다. 자세한 내용은 엄격한 형식 쿼리를 참조하세요.

4. 대화상자에서 저장을 클릭하여 차트를 저장하고 대시보드로 돌아갑니다.

코드 편집기 종료

차트 또는 조건을 저장하지 않고 코드 편집기를 종료하려면 쿼리 선택기 위젯으로 돌아가기를 클릭합니다. 편집기의 모든 쿼리 텍스트는 삭제되지만 클립보드에 저장할 수 있는 옵션이 제공됩니다.

엄격한 형식으로 쿼리 보기

코드 편집기를 사용할 때 엄격한 형식으로 쿼리를 보려면 추가 옵션을 클릭하고 엄격한 양식 보기를 선택합니다.

자세한 내용은 엄격한 형식 쿼리를 참조하세요.

시간 범위, 차트, 코드 편집기

알림 정책 조건에 사용되는 MQL 쿼리를 제외하고 코드 편집기의 MQL 쿼리에는 시간 범위가 포함되어야 합니다. 시간 범위는 쿼리의 일부로 반환할 데이터의 하위 집합을 지정합니다. 시간 범위는 차트의 시간 범위 선택기를 사용하여 암시적으로 표현하거나, MQL 쿼리 텍스트에 명시적으로 표시할 수 있습니다.

기본적으로 시간 범위 선택기는 1시간으로 설정되어 있습니다.

차트의 시간 범위를 변경하려면 시간 범위 선택기를 사용합니다. 예를 들어 지난주의 데이터를 보려면 시간 범위 선택기에서 지난 1주를 선택합니다. 시작 및 종료 시간을 지정하거나 살펴볼 시간을 지정할 수도 있습니다.

코드 편집기를 사용하여 알림 정책을 만드는 방법은 MQL 알림 정책 만들기를 참조하세요.

시간 선택에 차트 설정 사용

차트의 시간 선택기를 사용하여 쿼리 기간을 설정할 수 있습니다. 이 선택 도구가 기간을 설정하는 기본 방법입니다. 기간을 변경하려면 차트에서 다른 기간 옵션을 선택합니다. 예를 들어 일주일을 선택하면 쿼리에서 이 값을 기준으로 1주일 전의 데이터를 반환합니다.

이 기본 메커니즘을 사용하는 경우 쿼리 텍스트에 명시적 시간 범위를 지정할 필요가 없습니다. 차트의 값은 암시적으로 사용됩니다.

시간 선택에 within 사용

within 작업을 사용하여 쿼리에서 쿼리 기간을 명시적으로 지정할 수 있습니다. 이 작업은 반환된 데이터의 범위를 결정합니다. 쿼리에 within 작업이 포함된 경우 차트의 시간 선택 옵션이 비활성화되고 쿼리에 지정된 기간이 사용됩니다.

쿼리에서 명시적인 within 작업을 삭제하면 차트 옵션이 자동으로 다시 사용 설정되어 쿼리에 항상 기간이 포함됩니다.

API 메서드 timeSeries.query를 사용하여 쿼리를 실행하려면 명시적 시간 선택을 사용해야 합니다. 자세한 내용은 Monitoring API에서 MQL 사용을 참조하세요.

시간 설정 및 저장된 차트

MQL을 사용하여 차트를 만들고 차트에 대시보드에 저장하면 쿼리에 다음 두 가지 작업이 수행됩니다.

1. 편집기에서 입력한 쿼리는 정규 또는 엄격한 형식으로 변환됩니다. 변환은 쿼리의 의미를 변경하지 않지만, 전체 열 이름이나 정렬 작업과 같이 쿼리에서 가정하는 항목을 명시적으로 만듭니다. 자세한 내용은 엄격한 형식 쿼리를 참조하세요.

2. 쿼리의 기간 선택이 삭제됩니다. 대시보드의 차트는 시간 선택기를 공유하며 해당 선택기의 변경사항은 대시보드의 모든 차트에 적용됩니다. 따라서 원래 쿼리의 기간 선택기가 더 이상 필요하지 않습니다.

대시보드 관리 및 차트 수정에 대한 자세한 내용은 커스텀 대시보드 관리를 참조하세요.

쿼리, 정렬, 표시 기간

MQL에는 기간을 지정하는 잠재적으로 혼란을 줄 수 있는 작업이 여러 개 있습니다. 다음 작업은 쿼리 범위와 관련이 있습니다.

• within: 쿼리 출력 기간을 지정합니다. 이 작업은 반환되는 데이터 양을 결정합니다. 예를 들어 within 1h을 지정하면 쿼리는 마지막 1시간 내의 타임스탬프가 있는 지점만 생성하는데 이 작업이 차트의 시간 선택기 옵션을 재정의합니다.

• 다음 작업은 출력 테이블의 정렬 기간과 관련이 있습니다. 두 가지 모두 정렬된 테이블이 입력으로 필요하거나 기본값을 제공합니다.

  • every: 정렬된 테이블 출력의 기간을 지정합니다.

  • window: 정렬 작업의 기간을 지정합니다.

  두 경우 모두 align 작업이 명시적 정렬 기간과 함께 제공되는 경우 window 작업에 지정된 기간이 제공될 경우 해당 기간과 일치해야 합니다. delta 정렬 함수의 경우 정렬 기간(window)와 기간(period)은 동일해야 합니다. 명시적 정렬 기간이 주어진 경우 every 연산이 동의해야 합니다. 모든 경우 정렬 기간(window)은 정렬 기간(period)이상이어야 하고 그렇지 않으면 입력 데이터는 무시됩니다.

MQL에는 차트의 출력 포인트 기간을 지정하는 graph_period 연산이 있습니다. 이 작업은 결과가 서드 파티 소프트웨어가 출력을 차트화하는 API에 지정된 쿼리에 유용합니다. Monitoring 차트 작성 소프트웨어는 쿼리에서 graph_period 작업을 무시하여 출력 차트의 시간 폭에 따라 포인트의 기간을 설정합니다.

Monitoring 차트에서 그래프 기간은 차트의 시간 범위 선택기 값과 차트에 표시할 수 있는 최대 포인트 수를 기반으로 설정됩니다. 예를 들어 1주를 선택하면 그래프 기간이 1시간일 수 있습니다. 대시보드의 차트의 경우 그래프 기간을 보려면 쿼리 통계를 클릭합니다.

쿼리 정렬 기간과 그래프 기간 간의 관계를 통해 차트의 모양을 변경할 수 있습니다. 이 관계는 다음 섹션에서 설명합니다.

최소/최대 대역

쿼리 정렬 기간이 그래프 기간과 가까워지면 차트는 그래프로 표시된 각 시계열을 한 줄로 표시합니다. 쿼리 정렬 기간이 차트의 그래프 기간 중 절반 미만인 경우 차트의 각 선 주위에 음영 처리된 영역이 포함됩니다. 최소/최대 대역이라고 하는 이 리전은 평균값을 생성한 값 범위를 표시합니다.

예를 들어 다음과 같은 MQL 쿼리가 있다고 가정하겠습니다.

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

이 쿼리는 영역별로 VM의 평균 CPU 사용률을 1시간 정렬 기간으로 반환합니다.

차트의 시간 선택기를 1주로 설정하면 그래프 기간이 1시간으로 표시되고 이는 칩에 표시됩니다. 예시 쿼리에서는 그래프 기간 및 정렬 기간이 같습니다. 쿼리를 실행하면 다음과 같은 차트가 생성됩니다.

예를 들어 이전 쿼리에서 every 작업에 전달된 정렬 기간을 1h에서 1m로 변경하면 쿼리는 최소/최대 대역이 포함된 차트를 생성합니다.

차트 선은 차트의 1주 선택을 기반으로 1시간의 그래프 기간이 그래프로 표시되기 때문에 선은 이전 예시와 동일합니다. 그러나 쿼리는 1분마다 포인트를 생성하므로 최소/최대 대역은 각 1시간 그래프 포인트에 해당하는 쿼리의 1분 값 범위를 표시합니다.

every 작업이 생략된 경우 기본 쿼리 정렬 기간은 정렬 기간의 값 또는 정렬 기간이 지정되지 않은 경우 1분입니다.

MQL 기반 알림 정책

MQL 및 코드 편집기를 사용하여 알림 정책에 사용할 쿼리를 만들 수도 있습니다.

Google Cloud 콘솔에서 MQL 기반 알림 정책을 만들려면 알림 정책 관리에서 설명한 정책 만들기의 일반 단계를 따르되, 알림 정책의 조건을 만들 때는 양식 기반 측정항목 선택기 대신 코드 편집기를 사용합니다.

자세한 내용은 MQL 알림 정책 만들기를 참조하세요.

쿼리 변환

차트 또는 측정항목 탐색기에서 측정항목 선택기를 사용하여 쿼리를 만든 다음 해당 쿼리를 MQL로 변환할 수 있습니다. 해당하는 MQL 쿼리가 편집기에 표시됩니다.

측정항목 탐색기를 사용할 때 메뉴 빌드 쿼리를 MQL로 변환하려면 다음을 수행합니다.

1. 쿼리 빌더 창의 툴바에서 이름이  MQL 또는  PromQL인 버튼을 선택합니다.
2. 언어 전환 버튼에 MQL이 선택되어 있는지 확인합니다. 언어 전환 버튼은 쿼리 형식을 지정할 수 있는 동일한 툴바에 있습니다.

양식 기반 쿼리를 MQL로 변환하려면 대시보드에서 차트를 볼 때 MQL을 클릭합니다.

'Compute Engine VM 인스턴스에서 CPU 사용량 가져오기'와 같이 매우 간단한 요청을 고려합니다. 이 쿼리에는 gce_instance 모니터링 리소스 유형과 compute.googleapis.com/instance/cpu/usage_time 측정항목 유형이 포함됩니다.

다음 스크린샷은 양식 기반 측정항목 선택기에서 이 쿼리를 보여줍니다.

측정항목 및 모니터링 리소스 유형을 수동으로 입력했습니다. 다른 모든 필드에는 기본값이 있습니다.

다음 스크린샷은 양식 기반 선택을 MQL 쿼리로 변환한 결과를 보여줍니다.

MQL 쿼리는 특정 측정항목 및 리소스 유형의 시계열을 가져오고 1분 간격으로 비율 정렬을 수행합니다. 변환된 쿼리는 엄격한 형식입니다.

참고: MQL 표현을 다시 양식 기반 측정항목 선택기의 설정으로 변환할 수 없습니다. MQL은 측정항목 선택기로 빌드할 수 없는 쿼리를 지원합니다. 코드 편집기를 종료할 때 저장되지 않은 쿼리 텍스트는 삭제됩니다.