モニタリング フィルタ

このガイドでは、モニタリング フィルタを使用して、モニタリング対象リソース、指標タイプ、グループ定義、時系列を指定する方法について説明します。

指標、時系列、モニタリング対象リソースの概要については、指標、時系列、リソースをご覧ください。

フィルタはラベルを多用します。詳細については、ラベルをご覧ください。

フィルタの使用

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

  • 時系列を取得します。フィルタを使用して、データのプロジェクト、グループ、監視対象リソース特性、および指標特性に基づいて時系列データを選択します。詳細および例については、時系列データの取得を参照してください。

  • グループ内のリソースを定義します。フィルタを使用して、リソースのプロパティとそのリソースが属するプロジェクトに基づいて Group にリソースを割り当てます。詳細および例については、グループ メンバーを定義を参照してください。

  • グループ メンバーを一覧表示します。フィルタを使用して、リソース特性とリソースが属するプロジェクトに基づいてグループ内のリソースを選択します。詳細および例については、グループ メンバーの一覧表示を参照してください。)

  • 指標記述子を一覧表示します。フィルタを使用して、Monitoring 内にある数百の定義されたタイプから特定の指標タイプを検出します。詳細および例については、指標記述子の一覧表示を参照してください。

  • 監視対象リソース記述子を一覧表示します。フィルタを使用して、Monitoring 内にある数十の定義されたタイプから特定の監視対象リソースタイプを検出します。詳細および例については、監視対象リソース記述子の一覧表示を参照してください。

先述の操作のうちどれを制約するかによって、以下のリスト中のセレクタの論理 AND でフィルタを構成することができます。これらは簡単な例で、数種類の比較演算子があります。以下はその例です。

  • プロジェクト セレクタ: フィルタ照合を、メソッドの name パラメータ内で述べたワークスペース内の1 つ以上のプロジェクトに制限します。

    project = "project-id-or-number" OR project = "another-id-or-number"
    
  • グループ セレクタ: (単一の)Groupに属するリソースを照合します。例:

    group.id = "group-id"
    
  • リソース セレクタ: 特定のタイプの、または特定のラベル値を持つモニタリング対象リソースを照合します。例として、リソース情報を指定する異なる方法には次のようなものがあります。

    resource.type = "the_resource_type"
    resource.labels.a_label_for_the_resource_type = "label_value"
    
  • 指標セレクタ: フィルタを特定の指標タイプの、または特定のラベル値を持つ指標または時系列に制限します。例として、指標タイプを指定する異なる方法には次のようなものがあります。

    metric.type = "the_metric_type"
    metric.labels.a_label_for_the_metric_type = "label_value"
    

次の表は、使用するフィルタに基づいてどのセレクタがフィルタ内で許可されるかを示しています。

フィルタの目的 プロジェクト セレクタ グループ セレクタ リソース セレクタ 指標セレクタ
グループを定義 1
グループ メンバーを一覧表示
時系列を一覧表示 2
指標記述子を一覧表示
監視対象リソース記述子を一覧表示
1 グループ メンバーを定義するのに使用するときは、リソース セレクタには追加のオプションがあります。
2 時系列を一覧表示するときは、必ず 1 つの指標タイプを指定する必要があります。

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

時系列データの取得

メソッド: projects.timeSeries.list
フィルタ オブジェクト: projectgroup.idresource.typeresource.labels.[KEY]metric.typemetric.labels.[KEY]

時系列は、指標記述子により定義され、監視対象リソースオブジェクトを含みます。フィルタは指標セレクタを含む必要があり、そのセレクタは必ず 1 つの指標タイプを指定する必要があります。

  • 特定の指標タイプのすべての時系列:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
    
  • 特定のグループ内のリソースに関連する時系列。group セレクタは、アライメントされた時系列データでのみ機能します。詳細については、グループ セレクタをご覧ください。

    group.id = "2468013579" AND
        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"
    
  • 同様の名前のついた Compute Engine インスタンスからの時系列:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
        metric.labels.instance_name = starts_with("frontend-")
    

グループ メンバーを定義

メソッド: projects.groups
フィルタ オブジェクト: projectresource.typeresource.labels.keymetadata.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
フィルタ オブジェクト: projectresource.typeresource.labels.[KEY]

フィルタを使用して、どのグループ メンバーを取得するかを制限します。メソッドの name パラメータは、ワークスペースとワークスペースで定義されたグループを指定します。project オブジェクトをフィルタで使用する場合は、ワークスペースのメンバーであるプロジェクトを指定する必要があります。

  • プロジェクト my-project に属するすべての Cloud Pub/Sub トピックリソース:

    project = "{my-project}" AND resource.type = "pubsub_topic"
    

指標記述子の一覧表示

メソッド: projects.metricDescriptors.list
フィルタ オブジェクト: projectmetric.type

フィルタを使用して、どの指標記述子を取得するかを制限します。

  • すべての Compute Engine 指標:

    metric.type = starts_with("compute.googleapis.com")
    

Monitoring で定義される指標タイプの完全なリストについては、指標リストをご覧ください。指標の命名方法の概要については、命名規則と要件をご覧ください。

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

メソッド: projects.monitoredResourceDescriptors.list
フィルタ オブジェクト: resource.type

フィルタを使用して、どの監視対象リソース記述子を取得するかを制限します。

  • すべての Cloud Pub/Sub 監視対象リソース記述子。

    resource.type = starts_with("pubsub")
    

Monitoring で定義されるモニタリング対象リソースタイプの完全なリストについては、モニタリング対象リソースのリストをご覧ください。

参考: フィルタ構文

フィルタの概要と例については、フィルタの使用を参照してください。

モニタリング フィルタは、最大 4 つのタイプのセレクタからなる文字列です。

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

フィルタに含まれるセレクタのすべてが項目に一致した場合に、フィルタはその項目に一致したことになります。次のセクションで説明するように、一部のセレクタには、ANDOR で連結された複数の比較対照があります。

フィルタの目的によっては、特定のセレクタが、必須、省略可能、または禁止される可能性があります。たとえば、グループは指標タイプや時系列を含まないため、グループ内のリソースを定義するフィルタは、指標セレクタを含むことができません。一方、時系列を一覧表示するために使用されるフィルタは、指標セレクタを含む必要があります。フィルタ内のセレクタの順序は関係ありませんが、別のセレクタの比較対照が混在してはいけません。

比較対照

フィルタとそのセレクタは比較対照から構築されています。各比較対照は、以下の形式を持っています。

[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] は zoneinstance_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>)
                 #   one_of(<string>,...,<string>) for up to 100 strings
    

次の演算子を使用して比較対照をグループ分けしたり修正することができます。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          # 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 の呼び出しには perSeriesAligneralignmentPeriod の値を含める必要があります。これは、グループ メンバー自体が指標データと連結される必要のある時系列の一種であり、アライメント パラメータを供給することによって、その連結をどのように行うかを制御することができるためです。 アライメント パラメータの詳細については、データの集計をご覧ください。

リソース セレクタ

リソース セレクタは、フィルタ選択を特定のリソースタイプまたはラベル値を持つリソース―またはリソースに関連付けられた項目―に制限します。

<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> 構文の拡張機能を使用します。

  1. metadata.system_labels.[KEY]metadata.user_labels.[KEYSTRING] は、resource.labels.[KEY] と同じように比較で使用できます。metadata.user_labels のキーは、ハイフンなどの特殊文字を含めることができるため、引用符で囲む必要があります。

  2. 等しくない演算子(!=)を使用して、リソースタイプ、リソースラベル、メタデータを比較できます。演算子は、文字列、数値、ブール値、または部分文字列関数を比較するときに使用することができます。たとえば、リソースタイプが "gce" で始まっていない場合、resource.type!=starts_with("gce")は true です。

  3. あらゆるリソース比較対照の前で単一の NOT 演算子を使用することができます。たとえば、リソースのゾーンに "europe" が含まれていない場合、NOT resource.labels.zone:"europe" は true です。括弧で囲まれた語句の前で NOT を使用することはできません。

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