이 페이지의 일부 또는 모든 정보는 Trusted Cloud by S3NS에 적용되지 않을 수 있습니다.

모니터링 필터

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

시작하기 전에

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

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

필터 사용

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

list API 요청에서 반환된 특정 시계열 데이터를 선택합니다. 필터는 데이터의 모니터링 리소스 속성, 측정항목 속성을 기준으로 시계열을 선택할 수 있습니다. 자세한 내용과 예시는 시계열 데이터 검색을 참조하세요.

특정 측정항목 유형을 나열합니다. 자세한 내용과 예시는 측정항목 설명 나열을 참조하세요.
특정 모니터링 리소스 유형을 나열합니다. 자세한 내용과 예시는 모니터링 리소스 설명 나열을 참조하세요.

필터 선택기

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

resource: 특정 유형의 또는 특정 라벨 값이 있는 모니터링 리소스를 일치시킵니다.
- 다음 필터는 Compute Engine 가상 머신(VM) 인스턴스인 모든 모니터링 리소스를 일치시킵니다.
```
resource.type = "gce_instance"
```
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 호출을 기반으로 필터에 허용되는 선택기를 보여줍니다.

필터 목적	`resource` selector	`metric` selector
시계열 나열	예	예 ^*
측정항목 설명자 나열		예
모니터링 리소스 설명자 나열	예

^* 시계열을 나열할 때는 정확하게 측정항목 유형 하나를 지정해야 합니다.

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

시계열 데이터 검색

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

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

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

특정 측정항목 유형의 모든 시계열을 반환하려면 다음 명령어를 실행합니다.
```
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"

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

참조: 필터 문법

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

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

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

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

필터의 목적에 따라 특정 선택기가 필요하거나 선택사항이거나 금지될 수 있습니다. 예를 들어 시계열을 나열하는 데 사용되는 필터에는 측정항목 선택기가 포함되어야 합니다.

비교

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

[OBJECT]: 테스트할 값을 다음 중 하나로 선택합니다.
```
metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]
    
```
[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")

필터 선택기

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

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

리소스 선택기

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

<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개 이상 사용하는 경우 가독성을 높이기 위해 모두 괄호로 묶습니다.

측정항목 선택기

측정항목 선택 도구는 측정항목 유형 및 측정항목 라벨을 제한하여 특정 측정항목 또는 측정항목 설명을 지정합니다. 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")