モニタリングフィルタ

このガイドでは、Monitoring API を使用する際にフィルタを構成する方法について説明します。フィルタを使用して、モニタリング対象リソース、指標タイプ、グループ定義、時系列を指定します。フィルタを使用して、システムで実行されているプロセスをモニタリングするアラートポリシーを構成することもできます。これらのフィルタについては、プロセスの状態のフィルタをご覧ください。

始める前に

指標、時系列、モニタリング対象リソースについてよく理解していない場合は、指標、時系列、リソースをご覧ください。

ラベルの概要については、ラベルをご覧ください。

フィルタの使用

Monitoring API 内でフィルタを使用すると、次のことができます。

list API リクエストから返された特定の時系列データを選択します。フィルタで、データのプロジェクト、グループ、モニタリング対象リソースプロパティ、指標のプロパティに基づいて時系列を選択できます。詳細および例については、時系列データの取得をご覧ください。

リソースのプロパティとリソースが属するプロジェクトに基づいて、Group にリソースを割り当てます。詳細および例については、グループメンバーを定義をご覧ください。
リソースのプロパティに基づいて、グループ内のリソースを選択します。詳細および例については、グループメンバーの一覧表示をご覧ください。

特定の指標タイプを一覧表示します。詳細および例については、指標記述子の一覧表示をご覧ください。
特定のモニタリング対象リソースタイプを一覧表示します。詳細および例については、モニタリング対象リソース記述子の一覧表示をご覧ください。

フィルタセレクタ

フィルタは、少なくとも 1 つのセレクタ（フィルタキーワード）で構成されます。次の例では、さまざまなセレクタを示します。

project: 指定されたプロジェクトの指標が、name パラメータで表される指標スコープのスコーピングプロジェクトに表示可能な場合に一致します。

Google Cloud プロジェクトで複数の Google Cloud プロジェクトまたは AWS アカウントの指標を表示でき、単一のプロジェクトの指標のみが必要な場合は、project セレクタを使用します。たとえば、Project-A の指標スコープに Project-B が含まれている場合、name の値が Project-A で、かつ次のフィルタを使用する場合に一致が発生します。
```
project = "Project-B"
```
group: 1 つの 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` セレクタ	`group` セレクタ	`resource` セレクタ	`metric` セレクタ
グループを定義	○		○^*
グループメンバーを一覧表示	○		○
時系列を一覧表示	○	○	○	○ ^†
指標記述子を一覧表示	○			○
監視対象リソース記述子を一覧表示			○

^* グループメンバーを定義するのに使用するときは、リソースセレクタには追加のオプションがあります。
^† 時系列を一覧表示するときは、必ず 1 つの指標タイプを指定する必要があります。

次のセクションでは、モニタリングフィルタの代表的な使用例を示します。使用可能なフィルタオブジェクトおよび演算子の詳しい説明については、フィルタ構文を参照してください。

時系列データの取得

メソッド: projects.timeSeries.list
フィルタオブジェクト: project、group.id、resource.type、resource.labels.[KEY]、metric.type、metric.labels.[KEY]

時系列は、特定のモニタリング対象リソースからの指標タイプのタイムスタンプが付いたデータポイントのリストです。詳細については、指標モデルをご覧ください。指標タイプは指標記述子によって指定され、モニタリング対象リソースはモニタリング対象リソース記述子によって指定されます。

timeSeries.list メソッドに指定されるフィルタには、metric セレクタを含める必要があり、そのセレクタは必ず 1 つの指標タイプを指定する必要があります。

特定の指標タイプのすべての時系列を返すには:

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.create
フィルタオブジェクト: 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-")

グループの削除、更新、一覧表示に使用できる API メソッドについては、projects.groups API リファレンスページをご覧ください。

グループメンバーの一覧表示

メソッド: projects.groups.members.list
フィルタオブジェクト: project、resource.type、resource.labels.[KEY]

name パラメータで、指標スコープのスコーピングプロジェクトと、そのプロジェクトで定義されているグループを指定します。フィルタを指定しない場合、projects.groups.members.list はグループのメンバーシップのリストを返します。

フィルタを使用して、どのグループメンバーを取得するかを制限できます。フィルタに project セレクタが含まれている場合、セレクタの値は、スコーピングプロジェクトに指標が表示されるプロジェクトを指定する必要があります。無効な値が指定されている場合、project セレクタは無視されます。

たとえば、名前に test を含むすべてのリソースを含むグループを作成するとします。Pub/Sub トピックであるグループメンバーのみを一覧表示するには、次のフィルタを使用します。

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

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

リクエストを 1 つのインスタンスに制限するには、そのインスタンスを指定します。

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>)
    
```
timeSeries.list メソッドで使用される場合を除き、has_substring フィルタは 2 番目の引数をオプションとして取ります。これにより、一致において大文字と小文字を区別するかどうかを指定します。デフォルト値は 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 を使用できますが、既存の演算子（:）またはかっこで囲まれた式の前では使用できません。

NOT          # negates the following comparison

フィルタセレクタ

セレクタを使用して、フィルタ選択を特定の項目に制限します。続くセクションでは、中括弧は繰り返しを示すために使用されています。たとえば、<x> {OR <y>} という表記は、次のいずれかを記述できることを意味します。

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

プロジェクトセレクタ

プロジェクトセレクタは、フィルタ選択を単一のプロジェクトまたはプロジェクトのセットのいずれか 1 つに属する項目に制限します。各プロジェクトは、その ID または番号で指定することが可能です。

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

プロジェクトセレクタに 1 つ以上の比較対照がある場合は、読みやすくするために、セレクタ全体を括弧で囲みます。次に例を示します。

(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> を使用する場合は、読みやすくするためにすべてをかっこで囲みます。たとえば、次のフィルタを使用して、米国およびヨーロッパ内のすべての 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 です。既存の演算子（:）またはかっこで囲まれた式の前で NOT を使用することはできません。
exists 演算子（:）を使用して、キーの存在をテストできます。たとえば、ラベルキー zone がリソースに存在する場合、比較 resource.labels:zone は true です。

たとえば、VM インスタンスのプラットフォームリソースメタデータキーの 1 つが 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")

モニタリング フィルタ

始める前に

フィルタの使用

フィルタ セレクタ

時系列データの取得

グループ メンバーを定義

グループ メンバーの一覧表示

指標記述子の一覧表示

監視対象リソース記述子の一覧表示

例

指標検索例

グループでのフィルタリング

参考: フィルタ構文

比較

フィルタ セレクタ

プロジェクト セレクタ

グループ セレクタ

リソース セレクタ

グループ定義のためのリソース セレクタ

指標セレクタ

モニタリングフィルタ

フィルタセレクタ

グループメンバーを定義

グループメンバーの一覧表示

フィルタセレクタ

プロジェクトセレクタ

グループセレクタ

リソースセレクタ

グループ定義のためのリソースセレクタ