本指南說明使用 Monitoring API 時如何設定篩選器。您可以使用篩選器指定受監控的資源、指標類型、群組定義和時間序列。您也可以使用篩選器設定快訊政策，監控系統上執行的程序。如要瞭解這些篩選器，請參閱「程序健康狀態篩選器」。
事前準備
如果您不熟悉指標、時間序列和受監控資源，請參閱「指標、時間序列和資源」。
如果您不熟悉標籤，請參閱「標籤」一文瞭解簡介。
使用篩選器
您可以使用 Monitoring API 中的篩選器執行下列操作：
列出特定指標類型。如需更多資訊和範例，請參閱列出指標描述元。
列出特定受監控資源類型。如需詳細資訊和範例，請參閱「列出受監控資源描述元」。
篩選器選取器
篩選器至少包含一個選取器，也就是篩選器關鍵字。 以下範例說明不同的選取器：
-
project：當指定專案的指標可供name參數中提及的指標範圍限定範圍專案查看時，即為相符。如果 Google Cloud 專案 Google Cloud 可以查看多個專案或 AWS 帳戶的指標，但您只想查看單一專案的指標，請使用
project選取器。舉例來說，如果Project-A的指標範圍包含Project-B，當name的值為Project-A，且您使用下列篩選器時，就會發生比對：project = "Project-B"
-
group：比對屬於一個Group的資源。下列篩選器會比對 ID 為
group-id的群組：group.id = "group-id" -
resource：比對特定類型或具有特定標籤值的 受監控資源。-
下列篩選器會比對所有受監控的資源，這些資源是 Compute Engine 虛擬機器 (VM) 執行個體：
resource.type = "gce_instance"
-
下列篩選條件會比對區域開頭為
europe-的所有資源：resource.labels.zone = starts_with("europe-")
-
-
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 呼叫，篩選器中允許使用的選取器：
| 篩選用途 | project選取器 |
group選取器 |
resource選取器 |
metric選取器 |
|---|---|---|---|---|
| 定義群組 | 是 | 是* | ||
| 列出群組成員 | 是 | 是 | ||
| 列出時間序列 | 是 | 是 | 是 | yes † |
| 列出指標描述元 | 是 | 是 | ||
| 列出受監控的資源描述元 | 是 |
† 列出時間序列時，您必須指定一個指標類型。
以下各節將說明監控篩選器的常見用途。如需可用篩選器物件和運算子的完整討論，請參閱「篩選器語法」。
擷取時間序列資料
方法：
projects.timeSeries.list
篩選器物件：
project、group.id、resource.type、resource.labels.[KEY]、metric.type
metric.labels.[KEY]
時間序列是特定受控資源中，指標類型加上時間戳記的資料點清單。詳情請參閱「指標模型」。指標類型是由指標描述元指定，受監控的資源則是由受監控資源描述元指定。
為 timeSeries.list 方法指定的篩選器必須包含 metric 選取器，且該選取器必須指定一個指標類型：
- 如要傳回特定指標類型的所有時間序列：
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
如要傳回特定群組的所有時間序列，
group選取器僅適用於對齊的時間序列資料；詳情請參閱群組選取器：metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND group.id = "2468013579"
如要傳回特定 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.groups.create
篩選器物件：project、resource.type、resource.labels.key、
metadata.system_labels.[KEY]、metadata.user_labels.[KEY]
群組可包含任意數量的資源，具體取決於篩選條件。群組成員資格是動態的，每次評估篩選條件時，符合篩選條件的資源可能會變多或變少。Group 物件中的 name 參數會指定指標範圍的群組和範圍界定專案。如果篩選器使用 project 選擇器，則必須指定專案，且指標對範圍界定專案可見。
舉例來說，如要建立僅包含歐洲地區 Compute Engine 虛擬機器 (VM) 執行個體的群組，請使用下列篩選器：
resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")
如要瞭解可用於刪除、更新或列出群組的 API 方法，請參閱 projects.groups API 參考頁面。
商家資訊群組成員
方法：
projects.groups.members.list
篩選器物件：project、resource.type、resource.labels.[KEY]
name 參數會指定指標範圍的範圍設定專案，以及該專案中定義的群組。如果未指定篩選器，則 projects.groups.members.list 會傳回群組成員清單。
您可以使用篩選器，限制要擷取的群組成員。如果篩選器包含 project 選取器，則選取器值必須指定專案，且指標對範圍界定專案可見。如果指定的值無效，系統會忽略 project 選取器。
舉例來說，假設您建立的群組包含名稱含有 test 的所有資源。如要只列出 Pub/Sub 主題的群組成員，請使用下列篩選器：
resource.type = "pubsub_topic"
列出指標描述元
方法：
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"
使用群組篩選
下列範例說明如何在篩選器中使用群組選取器，將監控資源限制為特定群組中的資源。如要瞭解用於定義群組成員資格的選取器，請參閱群組定義的資源選取器。
{ "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"
參考資料：篩選器語法
如需篩選器總覽和範例，請參閱「使用篩選器」。
監控篩選器是字串，最多可包含四種選取器：
<monitoring_filter> ::= <project_selector> AND
<group_selector> AND
<resource_selector> AND
<metric_selector>
如果所有納入的選取器都與項目相符，篩選器就會比對項目。
如下列各節所述，部分選取器可透過 AND 或 OR 連結多項比較條件。篩選器中選取器的順序不重要，但不同選取器的比較不得混用。
視篩選器的用途而定，某些選取器可能是必要、選用或禁止使用。舉例來說，用於列出時間序列的篩選器必須包含指標選取器。 不過，定義群組中資源的篩選器不能包含指標選取器，因為群組不含指標類型或時間序列。
比較
篩選器及其選取器是根據比較結果建構而成。每項比較的格式如下：
-
[OBJECT]：選取要測試的值，可以是下列其中一個：
project group.id metric.type metric.labels.[KEY] resource.type resource.labels.[KEY] metadata.system_labels.[KEY] metadata.user_labels.[KEYSTRING][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")
NOT，但不能搭配 exists 運算子 (:) 使用，也不能在括號運算式之前使用：
NOT # negates the following comparison
篩選器選取器
使用選取器，將篩選器選項限制為特定項目。
在下列各節中，大括號用於表示重複。舉例來說，<x> {OR <y>} 標記表示您可以編寫下列任一項目：
<x> <x> OR <y> <x> OR <y> OR <y> <x> OR <y> OR <y> OR <y> ...
專案選取器
專案選取器會將篩選器選項限制為屬於單一專案或一組專案的項目。您可以透過 ID 或編號指定專案：
<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}
如果專案選取器有多個比較項目，請將整個選取器放在括號中，方便閱讀。例如：
(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 呼叫必須包含 perSeriesAligner 和 alignmentPeriod 欄位的值。這是因為群組成員本身就是一種時間序列，必須與指標資料合併，而提供對齊參數可讓您控管合併方式。如要進一步瞭解對齊參數，請參閱「匯總資料」。
資源選取器
資源選取器會將篩選器選項限制為具有特定資源類型或標籤值的資源 (或與資源相關聯的項目)：
<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>，請將所有選取器括在半形括號中，方便閱讀。舉例來說，下列篩選器可用於定義群組，其中包含美國和歐洲的所有 Compute Engine VM 執行個體。
resource.type = "gce_instance" AND
(resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))
群組定義的資源選取器
用於定義群組成員資格的資源選取器會使用 <resource_selector> 語法的擴充功能：
您可以根據中繼資料系統標籤 (
metadata.system_labels.[KEY]) 和中繼資料使用者標籤 (metadata.user_labels.[KEYSTRING]) 的值加入篩選器。建議您為metadata.user_labels的鍵加上引號，因為這些鍵可能含有連字號等特殊字元。如果選取器包含中繼資料篩選器和資源篩選器，您必須使用
AND合併兩者，不能使用OR。舉例來說，如果圖表具有下列選取器，則會顯示機器類型為e2-medium或e2-micro的所有 VM 執行個體的 CPU 使用率：metric.type="compute.googleapis.com/instance/cpu/utilization" resource.type="gce_instance" AND (metadata.system_labels."machine_type"="e2-medium" OR metadata.system_labels."machine_type"="e2-micro")
您可以使用不等於運算子 (
!=) 比較資源類型、資源標籤和中繼資料。比較字串、數字、布林值或子字串函式時，可以使用這個運算子。舉例來說，如果資源類型不是以"gce"開頭，則resource.type!=starts_with("gce")為 true。您可以在資源比較前使用單一
NOT運算子。舉例來說，如果資源的區域不包含"europe"，NOT resource.labels.zone="europe"就會是 true。您無法在 exists 運算子 (:) 或括號運算式之前使用NOT。您可以使用「exists」運算子 (
:) 測試索引鍵是否存在。 舉例來說，如果資源中存在標籤鍵zone，則比較resource.labels:zone為 true。
舉例來說，VM 執行個體的其中一個平台資源中繼資料鍵是 spot_instance。下列篩選器選取器會選擇隨機執行個體：
resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true
指標選取器
指標選擇器會限制指標類型和指標標籤，以指定特定指標或指標描述元。與 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")