監控篩選器

Cloud Monitoring API 中的篩選器可讓您在 API 要求中選取特定時間序列、指標類型和受監控資源。

事前準備

如果您不熟悉指標、時間序列和受監控資源，請參閱「指標、時間序列和資源」。

如果您不熟悉標籤，請參閱「標籤」一文。

使用篩選器

您可以在 Monitoring API 中使用篩選器，執行下列操作：

  • 選取從 list API 要求傳回的特定時間序列資料。篩選器可以根據資料的受監控資源屬性和指標屬性，選取時間序列。如需更多資訊和範例，請參閱「擷取時間序列資料」。

篩選條件選取器

篩選器至少包含一個「選取器」，也就是篩選器關鍵字。以下範例說明不同的選取器：

  • resource：比對特定類型或具有特定標籤值的 受監控資源。

    • 下列篩選器會比對所有屬於 Compute Engine 虛擬機器 (VM) 執行個體的受監控資源：

      resource.type = "gce_instance"

  • metric：比對特定 指標類型或時間序列，以及與特定值相符的特定標籤。

    • 下列篩選器會比對特定指標類型：

      metric.type = "compute.googleapis.com/instance/cpu/usage_time"

    • 下列篩選器會比對標籤名稱為 instance_name 且值開頭為 gke-hipster 或 gke-nginx 的時間序列：

      metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")

下表列出根據 Monitoring API 呼叫，篩選器中允許使用的選取器：

篩選用途 resource選取器 metric選取器
列出時間序列 是 是 *
列出指標描述元 是
列出受監控資源描述元 是
* 列出時間序列時，必須指定一個指標類型。

以下各節提供監控篩選器的常見用途範例。如需可用篩選器物件和運算子的完整討論，請參閱「篩選器語法」。

擷取時間序列資料

方法： projects.timeSeries.list
篩選器物件： project、resource.type、resource.labels.[KEY]、metric.type、 metric.labels.[KEY]

時間序列是特定受監控資源中，指標類型的時間戳記資料點清單。詳情請參閱「指標模型」。指標類型由指標描述元指定，受監控資源則由受監控資源描述元指定。

指定給 timeSeries.list 方法的篩選器必須包含 metric 選取器，且該選取器必須指定一個指標類型：

  • 如要傳回特定指標類型的所有時間序列，請使用下列篩選器：
    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")

如需 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 provided 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」的磁碟裝置讀取頻寬，請按照下列方式定義篩選器。這個篩選器會根據執行個體上是否存在該名稱的裝置，為每個執行個體傳回最多一個時間序列：

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"

如要將要求限制為單一執行個體，請指定該執行個體：

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"

參考資料：篩選器語法

如需篩選器總覽和範例，請參閱「使用篩選器」。

監控篩選器是由最多兩種選取器組成的字串：

    <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 篩選器會採用選用的第二個引數，指定比對是否忽略大小寫。預設值為 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")