モニタリング フィルタ

このガイドでは、監視対象リソース、指標、および時系列のセットを識別するためのモニタリング フィルタの使用について説明します。フィルタは、ListTimeSeries クエリ内に返される結果のセットを制限することや、グループメンバを定義することなど、モニタリング操作に対する制約を指定するための強力なツールです。

指標、時系列、監視対象リソース、およびラベルの概要については、指標を参照してください。

フィルタの使用

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

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

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

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

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

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

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

  • プロジェクト セレクタ: フィルタ照合をメソッドの name パラメータ内で述べた Stackdriver アカウント内の 1 つ以上のプロジェクトに属するオブジェクトに制限します。

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

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

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

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

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

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

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

時系列データの取得

メソッド: projects.timeSeries.list
フィルタ オブジェクト: projectgroup.idresource.typeresource.label.<key>metric.typemetric.label.<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.label.instance_name = "my-instance-name"
    
  • 同様の名前のついた Compute Engine インスタンスからの時系列:

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

グループ メンバーを定義

メソッド: projects.groups
フィルタ オブジェクト: projectresource.typeresource.label.keyresource.metadata.<key>resource.metadata.tag.<key>

グループは、フィルタによって指定されることにより、リソースをいくつでも含むことができます。グループ メンバーは動的なため、フィルタの評価ごとに、フィルタと一致するリソースは少なくなったり、多くなったりします。グループ オブジェクト内の name パラメータは、グループおよび所有する Stackdriver アカウントを指定します。project オブジェクトをフィルタ内で使用する場合、アカウントのメンバーであるプロジェクトを指定する必要があります。

  • ヨーロッパ内のすべての Compute Engine VM インスタンス:

    resource.type = "gce_instance" AND resource.label.zone = starts_with("europe-")
    

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

メソッド: projects.groups.members.list
フィルタ オブジェクト: projectresource.typeresource.label.<key>

フィルタを使用して、どのグループ メンバーを取得するかを制限します。メソッドに対する name パラメータは、Stackdriver アカウントとアカウント内で定義されたグループを指定します。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")
    

Stackdriver Monitoring によって定義される指標タイプの詳細リストについては、指標リストを参照してください。指標に名前を付ける方法の概要については、指標名を参照してください。

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

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

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

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

    resource.type = starts_with("pubsub")
    

Stackdriver Monitoring によって定義される監視対象リソースタイプの詳細リストについては、監視対象リソースリストを参照してください。

参考: フィルタ構文

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

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

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

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

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

比較対照

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

<object> <op> <value>

<object> は、セレクタの種類を指定します。セレクタの種類は、次のいずれかになります。

project
group.id
metric.type
metric.label.<key>
resource.type
resource.label.<key>
resource.metadata.<key>          (Group definitions only)
resource.metadata.tag.<string>   (Group definitions only)

表記 <key> は、ラベルセットで定義された名前を表します。たとえば、zone があります。比較演算子 <op> は、次のいずれかになります。

:            # substring match (case-sensitive)
=            # equality (case-sensitive)
> < >= <=    # numeric ordering
!=           # (Group definitions only) not equal
:            # (Group definitions only) substring match and test for key

<value> には、次のタイプがあります。

<string>     # "a Unicode string". Don't use apostrophes (`'`) to quote strings.
<bool>       # true or false
<number>     # 0, -2, 123456, 3.14156
<function>   # substring operators on the right side of '=' or '!=':
             #   starts_with(<string>)
             #   ends_with(<string>)

次の演算子を使用して比較対照をグループ分けしたり修正することができます。ORAND よりも優先順位が高く、演算子は大文字で記述する必要があります。

(...)        # grouping comparisons
AND          # conjunction (optional but recommended)
OR           # disjunction

AND 演算子は、演算子間で省略することも可能ですが、演算子を含めたほうがより明確で、エラーが発生しにくくなります。

グループ定義内でのみ、比較対照の前に単項否定演算子を使用することができますが、括弧内の語句の前では使用できません。

NOT          # (Group definitions only) 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.label.<key> '=' (<string> | <bool>)
                       | resource.label.<key> ':' <string>
                       | resource.label.<key> '=' (starts_with | ends_with) '(' <string> ')'
                       | resource.label.<key> ('=' | '>' | '<' | '>=' | '<=') <number>

セレクタ内に1 つ以上の <r_label_comparison> を使用している場合、読みやすいように、それらをすべて括弧で囲んでください。たとえば、次のフィルタを使用して、米国およびヨーロッパ内のすべての VM インスタンスを含むグループを定義することができます。

resource.type = "gce_instance" AND
  (resource.label.zone = starts_with("us-") OR resource.label.zone = starts_with("europe-"))

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

グループ メンバーを定義するために使用されるリソース セレクタは、<resource_selector> 構文の拡張機能を使用します。

  1. 名前 resource.metadata.<key>resource.metadata.tag.<string>resource.label.<key> と同様に比較対照に使用することができます。これにより、リソースに関連付けられたリソース メタデータにアクセスできるようになります。resource.metadata.tag のキーは、ハイフンなどの特殊文字を含むことができ、引用符で囲む必要があります。

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

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

  4. exists 演算子(:)を使用して、キーの存在をテストすることができます。たとえば、比較対照 resource.label:zone は、ラベルキー zone がリソース内に存在する場合は真です。

たとえば、VM インスタンスのプラットフォーム リソース メタデータ キーのうちの 1 つは spot_instance です。次のフィルタ セレクタは、スポット インスタンスであるインスタンスを選択します。

    resource.type = "gce_instance" AND resource.metadata.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> ::= <m_label_comparison> {[AND] <m_label_comparison>}
                            | <m_label_comparison> {OR <m_label_comparison>}

<m_label_comparison> ::= metric.label.<key> '=' <string> | <bool>
                       | metric.label.<key> ':' <string>
                       | metric.label.<key> '=' starts_with '(' <string> ')'
                       | metric.label.<key> '=' ends_with '(' <string> ')'
                       | metric.label.<key> ('=' | '>' | '<' | '>=' | '<=') <number>

セレクタ内に 2 つ以上の <m_label_comparison> がある場合は、読みやすいように括弧で囲んでください。たとえば、次のフィルタを使用して、特定のデータベース インスタンスの時系列を取得することができます。

metric.type = "cloudsql.googleapis.com/database/state" AND
  (metric.label.resource_type = "instance"
   metric.label.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.label.device_name = "log_partition"

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

resource.type = "gce_instance" AND
resource.label.instance_id = "1472038649266883453" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.label.device_name = "log_partition"

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

以下の例では、フィルタ内のグループ セレクタを使用して、監視対象リソースを特定のリソースに制限することを説明します。グループ メンバーを定義するために使用されるセレクタの詳細については、グループ定義を参照してください。

{ "name": "projects/my-stackdriver-account/groups/024681012",
  "display_name": "My Redis Cluster",
  "filter": "resource.metadata.tag.role=redis" }

projects.timeSeries.list メソッドの呼び出しでは、次のフィルタは、特定のグループ内のすべての Compute Engine インスタンスに対してディスク読み取り帯域幅の使用をリクエストします。グループは、メソッドの name パラメータ中で指定される Stackdriver アカウントで定義する必要があります。

resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。