モニタリング フィルタ

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

始める前に

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

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

フィルタの使用

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

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

フィルタ セレクタ

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

  • resource: 特定のタイプまたは特定のラベルの値を持つモニタリング対象リソースと照合します。

    • 次のフィルタは、Compute Engine 仮想マシン（VM）インスタンスであるすべてのモニタリング対象リソースを照合します。

      resource.type = "gce_instance"

  • 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 呼び出しに基づいてフィルタで許可されるセレクタを示します。

フィルタの目的 resource セレクタ metric セレクタ
時系列を一覧表示 ○ ○ *
指標記述子を一覧表示 ○
監視対象リソース記述子を一覧表示 ○
* 時系列を一覧表示するときは、必ず 1 つの指標タイプを指定する必要があります。

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

時系列データの取得

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

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

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

  • 特定の指標タイプのすべての時系列を返すには:
    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"

  • 名前が 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.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"

参考: フィルタ構文

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

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

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

フィルタに含まれるセレクタのすべてが項目に一致した場合に、フィルタはその項目に一致したことになります。続くセクションで説明するように、一部のセレクタには、AND や OR で連結された複数の比較対照があります。フィルタ内のセレクタの順序は重要ではありませんが、異なるセレクタの比較対照が混在してはいけません。

フィルタの目的によっては、特定のセレクタが、必須、省略可能、または禁止される可能性があります。たとえば、時系列を一覧表示するために使用されるフィルタは、指標セレクタを含む必要があります。

比較

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

  • [OBJECT]: 次のいずれかから、テストする値を選択します。

    metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]

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

フィルタ セレクタ

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

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

リソース セレクタ

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

<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> を使用する場合は、読みやすくするためにすべてをかっこで囲みます。

指標セレクタ

指標セレクタは、指標タイプと指標ラベルを制限することによって、特定の指標または指標記述子を指定します。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")