모니터링 필터

이 가이드에서는 모니터링 필터를 사용하여 모니터링 리소스, 측정항목 유형, 그룹 정의, 시계열을 지정합니다.

측정항목, 시계열, 모니터링 리소스에 대한 소개는 측정항목, 시계열, 리소스를 참조하세요.

필터는 라벨을 광범위하게 사용합니다. 자세한 내용은 라벨을 참조하세요.

필터 사용

Monitoring API v3의 필터를 사용하여 다음을 수행할 수 있습니다.

  • 시계열 검색. 필터를 사용하여 데이터의 프로젝트, 그룹, 모니터링 리소스 속성, 측정항목 속성을 기반으로 시계열 데이터를 선택합니다. 자세한 내용과 예시는 시계열 데이터 검색을 참조하세요.

  • 그룹의 리소스 정의. 필터를 사용하여 리소스의 속성과 리소스가 속한 프로젝트를 기반으로 Group에 리소스를 할당합니다. 자세한 내용 및 예시는 그룹 구성원 정의를 참조하세요.

  • 그룹 구성원 나열. 필터를 사용하여 리소스 속성 및 리소스가 속한 프로젝트를 기반으로 그룹 내의 리소스를 선택합니다. 자세한 내용 및 예시는 그룹 회원 나열을 참조하세요.

  • 측정항목 설명 나열. 필터를 사용하여 Monitoring에서 정의된 수백 가지 유형의 특정 측정항목 유형을 검사합니다. 자세한 내용과 예시는 측정항목 설명 나열을 참조하세요.

  • 모니터링 리소스 설명자 나열. 필터를 사용하여 Monitoring에서 정의된 수십 가지 유형의 특정 모니터링 리소스 유형을 검사합니다. 자세한 내용과 예시는 모니터링 리소스 설명자 나열을 참조하세요.

제한하는 이전 작업에 따라 필터는 다음 목록에 있는 선택기의 논리 AND로 구성될 수 있습니다. 다음은 간단한 예시입니다. 예를 들어 여러 종류의 비교 연산자가 있습니다.

  • 프로젝트 선택기: 메서드의 name 매개변수에 언급된 작업공간 내에서 하나 이상의 프로젝트에 속하는 객체로 필터 일치를 제한합니다.

    project = "project-id-or-number" OR project = "another-id-or-number"
    
  • 그룹 선택기: (단일) Group에 속하는 리소스와 일치합니다. 예:

    group.id = "group-id"
    
  • 리소스 선택기: 특정 유형 또는 특정 라벨 값의 모니터링 리소스와 일치합니다. 예를 들어 리소스 정보를 지정하는 방법은 다음과 같습니다.

    resource.type = "the_resource_type"
    resource.labels.a_label_for_the_resource_type = "label_value"
    
  • 측정항목 선택기: 필터를 특정 측정항목 유형의 측정항목 또는 시계열로 제한하거나 특정 라벨 값을 갖습니다. 예를 들어 측정항목 유형을 지정하는 방법은 다음과 같습니다.

    metric.type = "the_metric_type"
    metric.labels.a_label_for_the_metric_type = "label_value"
    

다음 표는 필터가 사용되는 작업에 따라 필터에서 허용되는 선택기를 보여줍니다.

필터 목적 프로젝트 선택기 그룹 선택기 리소스 선택기 측정항목 선택기
그룹 정의 1
그룹 구성원 나열
시계열 나열 2
측정항목 설명자 나열
모니터링 리소스 설명자 나열
1 리소스 선택기에는 그룹 구성원을 정의하는 데 사용할 수 있는 추가 옵션이 있습니다.
2 시계열을 나열할 때 정확히 하나의 측정항목 유형을 지정해야 합니다.

다음 섹션에서는 모니터링 필터의 일반적인 사용 예시를 보여줍니다. 사용 가능한 필터 객체 및 연산자에 대한 자세한 내용은 필터 구문을 참조하세요.

시계열 데이터 검색

메서드: projects.timeSeries.list
객체 필터링: project, group.id, resource.type, resource.labels.[KEY], metric.type, metric.labels.[KEY]

시계열은 특정 모니터링 리소스에서 어떤 측정항목 유형의 타임스탬프가 지정된 데이터 포인트의 목록입니다. 자세한 내용은 측정항목 모델을 참조하세요. 측정항목 유형은 측정항목 설명으로 지정하며, 모니터링 리소스는 모니터링 리소스 설명자로 지정합니다. 필터는 측정항목 선택기를 포함해야 하며 해당 선택기는 정확히 하나의 측정항목 유형을 지정해야 합니다.

  • 특정 측정항목 유형의 모든 시계열:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • 특정 그룹의 리소스와 관련된 시계열: group 선택기는 정렬된 시계열 데이터에서만 작동합니다. 자세한 내용은 그룹 선택기를 참조하세요.

    group.id = "2468013579" AND
        metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • 특정 Compute Engine 인스턴스의 시계열:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = "my-instance-name"
    
  • 이름이 비슷한 Compute Engine 인스턴스의 시계열:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = starts_with("frontend-")
    
  • gke-hipster 또는 gke-nginx로 시작하는 Compute Engine 인스턴스의 시계열:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
    

그룹 구성원 정의

메서드: projects.groups
객체 필터링: project, resource.type, resource.labels.key, metadata.system_labels.[KEY], metadata.user_labels.[KEY]

그룹에는 필터에 지정된 수만큼의 리소스가 포함될 수 있습니다. 그룹 구성원은 동적입니다. 필터가 평가될 때마다 필터와 일치하는 리소스가 더 많거나 적을 수 있습니다. Group 객체의 name 매개변수는 그룹 및 소유 작업공간을 지정합니다. project 객체가 필터에 사용되는 경우 작업공간의 구성원인 프로젝트를 지정해야 합니다.

  • 유럽의 모든 Compute Engine VM 인스턴스:

    resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")
    

그룹 회원 나열

메서드: projects.groups.members.list
객체 필터링: project, resource.type, resource.labels.[KEY]

필터를 사용하여 검색할 그룹 회원을 제한합니다. 메서드의 name 매개변수는 작업공간 및 작업공간에 정의된 그룹을 지정합니다. project 객체가 필터에 사용되는 경우 작업공간의 구성원인 프로젝트를 지정해야 합니다.

  • 프로젝트 my-project에 속하는 모든 Cloud Pub/Sub 주제 리소스:

    project = "{my-project}" AND resource.type = "pubsub_topic"
    

측정항목 설명 나열

메서드: projects.metricDescriptors.list
객체 필터링: project, metric.type

필터를 사용하여 검색할 측정항목 설명을 제한합니다.

  • 모든 Compute Engine 측정항목:

    metric.type = starts_with("compute.googleapis.com")
    

Monitoring에서 정의한 측정항목 유형의 전체 목록은 측정항목 목록을 참조하세요. 측정항목의 이름 지정 방법에 대한 개요는 이름 지정 규칙 및 요구사항을 참조하세요.

모니터링 리소스 설명자 나열

메서드: projects.monitoredResourceDescriptors.list
객체 필터링: resource.type

필터를 사용하여 검색할 모니터링 리소스 설명자를 제한합니다.

  • 모든 Cloud Pub/Sub 모니터링 리소스 설명자:

    resource.type = starts_with("pubsub")
    

Monitoring에서 정의한 모니터링 리소스 유형의 전체 목록은 모니터링 리소스 목록을 참조하세요.

참조: 필터 구문

예제가 포함된 필터에 대한 개요는 필터 사용을 참조하세요.

모니터링 필터는 최대 4가지 유형의 선택기로 구성된 문자열입니다.

<monitoring_filter> ::=  <project_selector> AND <group_selector> AND <resource_selector> AND <metric_selector>

포함된 선택기가 모두 항목과 일치하는 경우 필터가 항목과 일치합니다. 다음 섹션에 설명된 대로 일부 선택기는 AND 또는 OR를 결합한 여러 비교를 포함할 수 있습니다.

필터의 목적에 따라 특정 선택기가 필요하거나 선택사항이거나 금지될 수 있습니다. 예를 들어 그룹의 리소스를 정의하는 필터는 측정항목 유형 또는 시계열을 포함하지 않으므로 측정항목 선택기를 포함할 수 없습니다. 반면 시계열을 나열하는 데 사용되는 필터에는 측정항목 선택기가 포함되어야 합니다. 필터에서 선택기의 순서는 중요하지 않지만 여러 선택기의 비교를 섞어서는 안됩니다.

비교

필터와 선택기는 비교를 통해 빌드됩니다. 각 비교의 형식은 다음과 같습니다.

[OBJECT] [OPERATOR] [VALUE]

이러한 요소는 아래에 설명되어 있습니다.

  • [OBJECT]: 테스트할 값을 다음 중 하나로 선택합니다.

    project
    group.id
    metric.type
    metric.labels.[KEY]
    resource.type
    resource.labels.[KEY]
    metadata.system_labels.[KEY]
    metadata.user_labels.[KEYSTRING]
    

    [KEY]는 zone 또는 instance_id와 같은 이름입니다. [KEYSTRING]은 이름이 될 수 있지만 특수문자가 포함된 경우 따옴표(")로 묶어야 합니다.

  • [OPERATOR]: 다음 중 하나의 비교 연산자입니다.

    =            # equality (case-sensitive)
    > < >= <=    # numeric ordering
    !=           # not equal
    :            # "has" substring match and test for key (case-sensitive)
    
  • [VALUE]: 다음 중 하나의 리터럴 값 또는 기본 제공 함수 호출입니다.

    <string>     # "a Unicode string". Don't use apostrophes (`'`) to quote strings.
    <bool>       # true or false
    <number>     # 0, -2, 123456, 3.14156
    <function>   # operators on the right side of '=' or '!=':
                 #   starts_with(<string>)
                 #   ends_with(<string>)
                 #   has_substring(<string> [, ignore_case=false])
                 #   one_of(<string>,...,<string>) for up to 100 strings
                 #   monitoring.regex.full_match(<RE2-string>)
    

    timeSeries.list의 경우를 제외하면 has_substring 필터는 일치 항목이 대소문자를 무시하는지 여부를 지정하는 두 번째 인수(선택사항)를 사용합니다. 기본값은 false이므로 대소문자를 구분합니다.

    • 대소문자 구분: display_name=has_substring("Demo")
    • 대소문자 구분: display_name=has_substring("Demo", false)
    • 대소문자 구분 안 함: display_name=has_substring("Demo", true)

    timeSeries.list에는 has_substring(<string>) 형식만 지원됩니다.

    monitoring.regex.full_match 필터는 RE2 구문에서 정규 표현식 문자열을 사용합니다.

다음 연산자를 사용하여 비교를 그룹화하거나 수정할 수 있습니다. OR의 우선 순위가 AND보다 높습니다. 연산자는 대문자로 작성해야 합니다.

(...)        # grouping comparisons
AND          # conjunction (optional but recommended)
OR           # disjunction

연산자 간에 AND 연산자를 생략할 수 있지만, 포함하면 오류가 발생할 확률이 적으며 명확합니다.

x = one_of("a", "b", "c")의 비교는 다음과 동일합니다.

(x = "a" OR x = "b" OR x = "c")

그룹 정의에서만 비교 전에 단항 부정 연산자를 사용할 수 있지만 괄호로 묶은 표현식 앞에는 사용할 수 없습니다.

NOT          # negates the following comparison

필터 선택기

선택기를 사용하여 필터 선택을 특정 항목으로 제한합니다. 다음 섹션에서는 중괄호가 반복을 표시하는 데 사용됩니다. 예를 들어 <x> {OR <y>} 표기법은 다음과 같이 작성될 수 있습니다.

<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...

프로젝트 선택기

프로젝트 선택기는 단일 프로젝트 또는 프로젝트 집합 중 하나에 속하는 항목으로 필터 선택을 제한합니다. 각 프로젝트는 ID 또는 번호로 지정할 수 있습니다.

<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}

프로젝트 선택기에 비교가 둘 이상인 경우 가독성을 높이기 위해 전체 선택기를 괄호로 묶습니다. 예:

(project=12345 OR project="my-project-id") AND resource.type="gce_instance"

그룹 선택기

그룹 선택기는 필터 선택을 단일 그룹에 속한 항목으로 제한합니다.

<group_selector> ::= group.id '=' <string>

예를 들어 다음 필터를 사용하여 그룹의 각 VM 인스턴스에서 시계열을 검색할 수 있습니다.

group.id = 12345 AND
    resource.type = "gce_instance" AND
    metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

그룹 선택기는 projects.timeSeries.list에 전달된 필터에서만 허용됩니다. 또한 그룹을 선택하려면 정렬된 데이터가 필요합니다. 즉, projects.timeSeries.list에 대한 호출에는 perSeriesAligneralignmentPeriod 값이 포함되어야 합니다. 이는 그룹 구성원 자체가 측정항목 데이터와 조인해야 하는 시계열 유형이고 정렬 매개변수의 제공으로 조인이 수행되는 방식을 제어할 수 있기 때문입니다. 정렬 매개변수에 대한 자세한 내용은 데이터 집계를 참조하세요.

리소스 선택기

리소스 선택기는 필터 선택을 특정 리소스 유형 또는 라벨 값이 있는 리소스 또는 리소스와 연결된 항목으로 제한합니다.

<resource_selector> ::= <resource_type_expression>
                      | <resource_label_expression>
                      | <resource_type_expression> AND <resource_label_expression>

<resource_type_expression> ::= resource.type '=' <string>
                             | resource.type ':' <string>
                             | resource.type '=' starts_with '(' <string>')'
                             | resource.type '=' ends_with '(' <string> ')'

<resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}
                              | <r_label_comparison> {OR <r_label_comparison>}

<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)
                       | resource.labels.[KEY] ':' <string>
                       | resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'
                       | resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

선택기에서 둘 이상의 <r_label_comparison>을 사용하는 경우 가독성을 높이기 위해 모두 괄호로 묶습니다. 예를 들어 다음 필터는 미국과 유럽의 모든 VM 인스턴스를 포함하는 그룹을 정의하는 데 사용할 수 있습니다.

resource.type = "gce_instance" AND
  (resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))

그룹 정의를 위한 리소스 선택기

그룹 구성원을 정의하는 데 사용되는 리소스 선택기는 <resource_selector> 구문에 대한 확장 프로그램을 사용합니다.

  1. resource.labels.[KEY]와 같은 방식으로 비교할 때 metadata.system_labels.[KEY]metadata.user_labels.[KEYSTRING]라는 이름을 사용할 수 있습니다. metadata.user_labels의 키는 하이픈과 같은 특수문자를 포함할 수 있으므로 따옴표로 묶어야 합니다.

  2. 같지 않음의 연산자(!=)를 사용하여 리소스 유형, 리소스 라벨, 메타데이터를 비교할 수 있습니다. 연산자는 문자열, 숫자, 부울 또는 하위 문자열 함수를 비교할 때 사용할 수 있습니다. 예를 들어 리소스 유형이 "gce"로 시작하지 않으면 resource.type!=starts_with("gce")가 true입니다.

  3. 리소스 비교 전에 단일 NOT 연산자를 사용할 수 있습니다. 예를 들어 리소스의 영역에 "europe"이 없으면 NOT resource.labels.zone:"europe"이 true입니다. 괄호로 묶은 표현식 앞에는 NOT을 사용할 수 없습니다.

  4. 기존 연산자(:)를 사용하여 키가 있는지 테스트할 수 있습니다. 예를 들어 라벨 키 zone가 리소스에 있으면 비교 resource.labels.zone가 true입니다.

예를 들어 VM 인스턴스의 플랫폼 리소스 메타데이터 키 중 하나는 spot_instance입니다. 다음 필터 선택기는 스팟 인스턴스인 인스턴스를 선택합니다.

    resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true

측정항목 선택기

측정항목 선택 도구는 측정항목 유형 및 측정항목 라벨을 제한하여 특정 측정항목 또는 측정항목 설명을 지정합니다. 시계열 데이터를 나열할 때 측정항목 선택기는 단일 측정항목 유형을 지정해야 합니다.

<metric_selector> ::= <metric_name_expression> [AND <metric_label_expression>]

<metric_name_expression> ::= metric.type '=' <string>
                           | metric.type ':' <string>
                           | metric.type '=' starts_with '(' <string> ')'
                           | metric.type '=' ends_with '(' <string> ')'

<metric_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
                            | <metric_label_comparison> {OR <metric_label_comparison>}

<metric_label_comparison> ::= metric.labels.[KEY] '=' <string> | <bool>
                            | metric.labels.[KEY] ':' <string>
                            | metric.labels.[KEY] '=' starts_with '(' <string> ')'
                            | metric.labels.[KEY] '=' ends_with '(' <string> ')'
                            | metric.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>

예를 들어 다음 필터를 사용하여 특정 데이터베이스 인스턴스의 시계열을 검색할 수 있습니다.

metric.type = "cloudsql.googleapis.com/database/state" AND
  (metric.labels.resource_type = "instance" AND
   metric.labels.resource_id = "abc-123456")

필터링 예시에서는 이미지를 위해 간략화된 다음의 측정항목 설명, 모니터링 리소스 설명자, 가상 머신 인스턴스를 사용합니다.

# Metric descriptor:
{ "name": "projects/my-project-id/metricDescriptors/compute.googleapis.com%2Finstance%2Fdisk%2Fread_bytes_count"
  "type": "compute.googleapis.com/instance/disk/read_bytes_count",
  "labels": [ { "key": "device_name",
                "description": "The name of the disk device." } ] }

# Monitored resource descriptor:
{  "name": "monitoredResourceDescriptors/gce_instance"
   "type": "gce_instance",
   "labels": [
     { "key": "instance_id",
       "description": "The instance ID provide by Google Compute Engine." },
     { "key": "zone",
       "description": "The Google Cloud Platform zone hosting the instance."
     } ] }

# Resource descriptor for a virtual machine instance.
{ "type": "gce_instance",
  "instance_id": "1472038649266883453",
  "zone": "us-east-1b",
  "disks": [ "log_partition" ],
  "machine_type": "n1-standard-2",
  "tags": { "environment": "bleeding-edge",
            "role": "frobulator" },
  "project_id": "my-project-id" }

측정항목 검색의 예시

모든 인스턴스 및 모든 기기의 디스크 읽기 대역폭 사용량을 요청하려면 아래에 표시된 대로 필터를 정의합니다. 이렇게 하면 각 인스턴스에 대해 각 기기의 읽기 대역폭을 보고하는 별도의 시계열이 반환됩니다.

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

각 인스턴스에서 'log_partition'이라고 하는 디스크 기기에 대해서만 읽기 대역폭을 쿼리하도록 요청을 세분화하려면 다음과 같이 필터를 정의합니다. 이 필터는 인스턴스에 해당 이름의 기기가 있는지 여부에 따라 최대 1개의 시계열을 반환합니다.

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

요청을 단일 인스턴스로 제한하려면 해당 인스턴스를 지정합니다.

resource.type = "gce_instance" AND
resource.labels.instance_id = "1472038649266883453" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

그룹으로 필터링

다음 예시는 필터에서 그룹 선택기를 사용하여 모니터링 리소스를 특정 그룹의 리소스로 제한하는 방법을 보여줍니다. 그룹 구성원을 정의하는 데 사용되는 선택기에 대한 자세한 내용은 그룹 정의를 참조하세요.

{ "name": "projects/my-test-project/groups/024681012",
  "display_name": "My Redis Cluster",
  "filter": "metadata.user_labels.role=redis" }

projects.timeSeries.list에 대한 메서드 호출 시 다음 필터는 특정 그룹의 모든 Compute Engine 인스턴스에 대한 디스크 읽기 대역폭 사용량을 요청합니다. 그룹은 메서드의 name 매개변수에 지정된 작업공간에 정의되어야 합니다.

resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"