このガイドでは、Monitoring API 使用時にフィルタを構成する方法について説明します。フィルタを使用して、モニタリング対象リソース、指標タイプ、グループ定義、時系列を指定します。
フィルタを使用して、システムで実行されているプロセスをモニタリングするアラート ポリシーを構成することもできます。これらのフィルタの詳細については、プロセスの状態フィルタをご覧ください。
始める前に
指標、時系列、モニタリング対象リソースに精通されていない場合は、指標、時系列、リソースをご覧ください。
ラベルの概要については、ラベルをご覧ください。
フィルタの使用
Monitoring API 内でフィルタを使用すると、次のことができます。
listAPI リクエストから返された特定の時系列データを選択します。フィルタで、データのプロジェクト、グループ、モニタリング対象のリソース プロパティ、指標のプロパティに基づいて時系列を選択できます。詳細および例については、時系列データの取得を参照してください。リソースのプロパティとリソースが属するプロジェクトに基づいて、
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 selector |
group selector |
resource selector |
metric selector |
|---|---|---|---|---|
| グループを定義 | ○ | ○1 | ||
| グループ メンバーを一覧表示 | ○ | ○ | ||
| 時系列を一覧表示 | ○ | ○ | ○ | ○2 |
| 指標記述子を一覧表示 | ○ | ○ | ||
| 監視対象リソース記述子を一覧表示 | ○ |
2 時系列を一覧表示するときは、必ず 1 つの指標タイプを指定する必要があります。
次のセクションでは、モニタリング フィルタの代表的な使用例を示します。 使用可能なフィルタ オブジェクトおよび演算子の詳しい説明については、フィルタ構文を参照してください。
時系列データの取得
メソッド: projects.timeSeries.list
フィルタ オブジェクト: project、group.id、resource.type、resource.labels.[KEY]、metric.type、metric.labels.[KEY]
時系列は、特定のモニタリング対象リソースからの指標タイプのタイムスタンプが付いたデータポイントのリストです。詳細については、指標モデルをご覧ください。指標タイプは指標記述子によって指定され、モニタリング対象リソースはモニタリング対象リソース記述子によって指定されます。
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 パラメータで、グループと指標スコープのスコープ対象プロジェクトを指定します。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
フィルタを使用して、どの監視対象リソース記述子を取得するかを制限します。
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フィルタは 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> ')'
<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> 構文の拡張機能を使用します。
メタデータ システムラベル
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
指標セレクタ
指標セレクタは、指標タイプと指標ラベルを制限することによって、特定の指標または指標記述子を指定します。時系列データを一覧表示する場合、指標セレクタは、単一の指標タイプを指定する必要があります。
<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"
リクエストを 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"