모니터링 필터

이 가이드에서는 Monitoring API를 사용할 때 필터를 구성하는 방법을 설명합니다. 필터를 사용하여 모니터링 리소스, 측정항목 유형, 그룹 정의, 시계열을 지정합니다.

필터를 사용하여 시스템에서 실행 중인 프로세스를 모니터링하는 알림 정책을 구성할 수도 있습니다. 이러한 필터에 대한 자세한 내용은 프로세스 상태 필터를 참조하세요.

시작하기 전에

측정항목, 시계열, 모니터링 리소스에 익숙하지 않으면 측정항목, 시계열, 리소스를 참조하세요.

라벨을 잘 모른다면 라벨에 대한 소개를 참조하세요.

필터 사용

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

list API 요청에서 반환된 특정 시계열 데이터를 선택합니다. 필터는 데이터의 프로젝트, 그룹, 모니터링 리소스 속성, 측정항목 속성에 따라 시계열을 선택할 수 있습니다. 자세한 내용과 예시는 시계열 데이터 검색을 참조하세요.
리소스 속성과 속한 프로젝트를 기반으로 Group에 리소스를 할당합니다. 자세한 내용 및 예시는 그룹 멤버십 정의를 참조하세요.
리소스 속성과 속한 프로젝트를 기반으로 그룹 내 리소스를 선택합니다. 자세한 내용 및 예시는 그룹 멤버십 나열을 참조하세요.
특정 측정항목 유형을 나열합니다. 자세한 내용과 예시는 측정항목 설명 나열을 참조하세요.
특정 모니터링 리소스 유형을 나열합니다. 자세한 내용과 예시는 모니터링 리소스 설명 나열을 참조하세요.

필터 선택기

필터는 하나 이상의 선택기(필터 키워드)로 구성됩니다. 다음 예시에서는 다양한 선택기를 보여줍니다.

project: 지정된 프로젝트의 측정항목이 name 매개변수에 언급된 측정항목 범위의 범위 지정 프로젝트에 표시되는 경우에 일치시킵니다.

Google Cloud 프로젝트에서 여러 Google Cloud 프로젝트나 AWS 계정의 측정항목을 볼 수 있고 개발자가 단일 프로젝트의 측정항목만 원하는 경우에는 project 선택기를 사용합니다. 예를 들어 Project-A의 측정항목 범위에 Project-B가 포함된 경우 name 값이 Project-A이고 개발자가 다음 필터를 사용할 때 일치가 발생합니다.
```
project = "Project-B"
```
group: Group 하나에 속하는 리소스를 일치시킵니다.

다음 필터는 그룹과 group-id 식별자를 일치시킵니다.
```
group.id = "group-id"
    
```
resource: 특정 유형의 또는 특정 라벨 값이 있는 모니터링 리소스를 일치시킵니다.
- 다음 필터는 Compute Engine 가상 머신(VM) 인스턴스인 모든 모니터링 리소스를 일치시킵니다.
```
resource.type = "gce_instance"
```
- 다음 필터는 europe-로 시작하는 영역이 있는 모든 리소스를 일치시킵니다.
```
resource.labels.zone = starts_with("europe-")
```
metric: 특정 측정항목 유형 또는 특정 값과 일치하는 특정 라벨이 있는 시계열과 일치시킵니다.
- 다음 필터는 특정 측정항목 유형을 일치시킵니다.
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```
- 다음 필터는 gke-hipster 또는 gke-nginx로 시작하는 값이 있는 instance_name 라벨이 지정된 시계열을 일치시킵니다.
```
metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")
```

다음 표는 Monitoring API 호출을 기반으로 필터에 허용되는 선택기를 보여줍니다.

필터 목적	`project` selector	`group` selector	`resource` selector	`metric` selector
그룹 정의	예		예^*
그룹 구성원 나열	예		예
시계열 나열	예	예	예	예 ^†
측정항목 설명자 나열	예			예
모니터링 리소스 설명자 나열			예

^* 리소스 선택기에는 그룹 구성원을 정의하는 데 사용할 수 있는 추가 옵션이 있습니다.
^† 시계열을 나열할 때는 정확하게 측정항목 유형 하나를 지정해야 합니다.

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

시계열 데이터 검색

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

시계열은 특정 모니터링 리소스에서 측정항목 유형의 타임스탬프가 지정된 데이터 포인트의 목록입니다. 자세한 내용은 측정항목 모델을 참조하세요. 측정항목 유형은 측정항목 설명으로 지정되고 모니터링되는 리소스는 모니터링 리소스 설명으로 지정됩니다.

timeSeries.list 메서드에 지정된 필터에는 metric 선택기가 포함되어야 하며 이 선택기에서 정확하게 측정항목 유형 하나를 지정해야 합니다.

특정 측정항목 유형의 모든 시계열을 반환하려면 다음 명령어를 실행합니다.
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```
특정 그룹의 모든 시계열을 반환하려면 다음 명령어를 실행합니다. group 선택기는 정렬된 시계열 데이터에서만 작동합니다. 자세한 내용은 그룹 선택기를 참조하세요.
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
group.id = "2468013579"
```

특정 Compute Engine 인스턴스의 모든 시계열을 반환하려면 다음 필터를 사용합니다.

metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
metric.labels.instance_name = "my-instance-name"

frontend-로 시작하는 이름이 있는 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 매개변수는 측정항목 범위의 그룹과 범위]metrics-scope-concept를 지정합니다. 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에 속하는 모든 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")
```

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

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

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

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

Pub/Sub 모니터링 리소스 설명만 검색하려면 다음 필터를 사용합니다.
```
resource.type = starts_with("pubsub")
```

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

예시

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

    # 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"

참조: 필터 구문

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

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

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

포함된 선택기가 모두 항목과 일치하는 경우 필터가 항목과 일치합니다. 다음 섹션의 설명대로 일부 선택기는 AND 또는 OR를 결합하여 비교를 여러 개 포함할 수 있습니다. 필터에서 선택기 순서는 중요하지 않지만 여러 선택기의 비교를 섞어서는 안됩니다.

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

비교

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

[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>)
    
```
has_substring 필터는 timeSeries.list 메서드에 사용되는 경우를 제외하고 일치 항목이 대소문자를 무시하는지 여부를 지정하는 선택적 두 번째 인수를 사용합니다. 기본값은 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을 사용할 수 있지만 exists 연산자(:)나 괄호로 묶인 표현식 앞에서는 사용할 수 없습니다.

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 호출에는 perSeriesAligner 및 alignmentPeriod 필드의 값이 포함되어야 합니다. 이는 그룹 구성원 자체가 측정항목 데이터와 조인해야 하는 시계열 유형이고 정렬 매개변수의 제공으로 조인이 수행되는 방식을 제어할 수 있기 때문입니다. 정렬 매개변수에 대한 자세한 내용은 데이터 집계를 참조하세요.

리소스 선택기

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

<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> ')'

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

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

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

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

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

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

메타데이터 시스템 라벨 metadata.system_labels.[KEY] 및 메타데이터 사용자 라벨 metadata.user_labels.[KEYSTRING]의 값에 따라 필터를 포함합니다. metadata.user_labels 키에는 하이픈과 같은 특수문자를 포함될 수 있으므로 이 키를 따옴표로 묶는 것이 좋습니다.

선택기에 메타데이터 필터 및 리소스 필터가 포함된 경우 AND와 결합해야 합니다. OR을 사용할 수 없습니다. 예를 들어 다음 선택기가 포함된 차트에는 머신 유형이 e2-medium 또는 e2-micro인 모든 VM 인스턴스의 CPU 사용률이 표시됩니다.
```
metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" AND
(metadata.system_labels."machine_type"="e2-medium" OR
metadata.system_labels."machine_type"="e2-micro")
```
같지 않음의 연산자(!=)를 사용하여 리소스 유형, 리소스 라벨, 메타데이터를 비교할 수 있습니다. 연산자는 문자열, 숫자, 부울 또는 하위 문자열 함수를 비교할 때 사용할 수 있습니다. 예를 들어 리소스 유형이 "gce"로 시작하지 않으면 resource.type!=starts_with("gce")가 true입니다.
리소스 비교 앞에 단일 NOT 연산자를 사용할 수 있습니다. 예를 들어 리소스의 영역에 "europe"이 없으면 NOT resource.labels.zone="europe"이 true입니다. exists 연산자(:) 또는 괄호로 묶인 표현식 앞에는 NOT을 사용할 수 없습니다.
'exists' 연산자(:)를 사용하여 키가 있는지 테스트할 수 있습니다. 예를 들어 라벨 키 zone이 리소스에 있으면 비교 resource.labels:zone은 true입니다.

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

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

측정항목 선택기

측정항목 선택 도구는 측정항목 유형 및 측정항목 라벨을 제한하여 특정 측정항목 또는 측정항목 설명을 지정합니다. projects.timeSeries.list 메서드와 함께 사용되는 경우에는 측정항목 선택기에서 단일 측정항목 유형을 지정해야 합니다.

<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_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_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
                            | <metric_label_comparison> {OR <metric_label_comparison>}

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

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