本頁面中的部分或全部資訊可能不適用於 Trusted Cloud by S3NS。

本頁面由 Cloud Translation API 翻譯而成。

監控篩選器

本指南說明如何在使用 Monitoring 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`選取器
列出時間序列	是	yes ^*
列出指標描述元		是
列出受監控的資源描述元	是

^* 列出時間序列時，您必須指定一個指標類型。

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

擷取時間序列資料

方法： 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 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」的磁碟裝置讀取頻寬，請定義篩選器如下。這個篩選器會針對每個執行個體傳回最多一個時間序列，具體取決於該執行個體上是否有該名稱的裝置：

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