このガイドでは、Monitoring API を使用する際のフィルタの構成方法について説明します。フィルタを使用して、モニタリング対象リソース、指標タイプ、グループ定義、時系列を指定します。フィルタを使用して、システムで実行されているプロセスをモニタリングするアラート ポリシーを構成することもできます。これらのフィルタの詳細については、プロセスの状態のフィルタをご覧ください。
始める前に
指標、時系列、モニタリング対象リソースに精通されていない場合は、指標、時系列、リソースをご覧ください。
ラベルの概要については、ラベルをご覧ください。
フィルタの使用
Monitoring API 内でフィルタを使用すると、次のことができます。
listAPI リクエストから返された特定の時系列データを選択します。 フィルタで、データのプロジェクト、グループ、モニタリング対象リソース プロパティ、指標のプロパティに基づいて時系列を選択できます。詳細および例については、時系列データの取得を参照してください。
リソースのプロパティとリソースが属するプロジェクトに基づいて、
Groupにリソースを割り当てます。詳細および例については、グループ メンバーを定義を参照してください。リソースのプロパティとリソースが属するプロジェクトに基づいて、グループ内のリソースを選択します。詳細および例については、グループ メンバーの一覧表示を参照してください。
特定の指標タイプを一覧表示します。詳細および例については、指標記述子の一覧表示を参照してください。
特定のモニタリング対象リソースタイプを一覧表示します。詳細および例については、モニタリング対象リソース記述子の一覧表示を参照してください。
フィルタ セレクタ
フィルタは、少なくとも 1 つのセレクタselector（フィルタ キーワード）で構成されます。次の例は、さまざまなセレクタについて説明しています。
-
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 selector |
group selector |
resource selector |
metric selector |
|---|---|---|---|---|
| グループを定義 | ○ | ○* | ||
| グループ メンバーを一覧表示 | ○ | ○ | ||
| 時系列を一覧表示 | ○ | ○ | ○ | ○ † |
| 指標記述子を一覧表示 | ○ | ○ | ||
| 監視対象リソース記述子を一覧表示 | ○ |
† 時系列を一覧表示するときは、必ず 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
フィルタ オブジェクト: project、resource.type、resource.labels.key、metadata.system_labels.[KEY]、metadata.user_labels.[KEY]
グループは、フィルタによって指定されることにより、リソースをいくつでも含むことができます。グループ メンバーは動的なため、フィルタの評価ごとに、フィルタと一致するリソースは少なくなったり、多くなったりします。Group オブジェクトの name パラメータは、指標スコープ metrics-scope-concept のグループとスコープ対象プロジェクトを指定します。project セレクタをフィルタで使用する場合は、スコープ対象プロジェクトに表示される指標を持つプロジェクトを指定する必要があります。
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"
リクエストを 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")