Cloud Monitoring API 中的篩選器可讓您在 API 要求、圖表和警告政策中，選取特定時間序列、指標類型、受監控資源和資源群組。如要在警告政策或圖表中計算虛擬機器上執行的程序，請改用程序健康狀態篩選器。
事前準備
如果您不熟悉指標、時間序列和受監控資源，請參閱「指標、時間序列和資源」。
如果您不熟悉標籤，請參閱「標籤」一文。
使用篩選器
您可以在 Monitoring API 中使用篩選器，執行下列操作：
列出特定指標類型。如需更多資訊和範例，請參閱「列出指標描述元」。
列出特定受監控資源類型。如需更多資訊和範例，請參閱「列出受監控資源描述元」。
篩選條件選取器
篩選器至少包含一個「選取器」，也就是篩選器關鍵字。以下範例說明不同的選取器：
-
project：如果指定專案的指標可供name參數中提及的指標範圍限定範圍專案查看，則符合條件。如果 Google Cloud 專案可以查看多個 Google Cloud 專案或 AWS 帳戶的指標，而您只想查看部分專案的指標，請使用
project選取器。舉例來說，如果Project-A的指標範圍包含Project-B，則當name的值為Project-A且您使用下列篩選器時，就會發生比對：project = "Project-B"
下列篩選器會比對任何開頭為
Project-的專案 ID：project = monitoring.regex.full_match("Project-.*") -
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選取器 |
|---|---|---|---|---|
| 定義群組 | 是 | 是* | ||
| 列出群組成員 | 是 | 是 | ||
| 列出時間序列 | 是 | 是 | 是 | 是 † |
| 列出指標描述元 | 是 | 是 | ||
| 列出受監控資源描述元 | 是 |
† 列出時間序列時，必須指定一個指標類型。
以下各節提供監控篩選器的常見用途範例。如需可用篩選器物件和運算子的完整討論，請參閱「篩選器語法」。
擷取時間序列資料
方法：
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 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"
使用群組篩選
以下範例說明如何在篩選器中使用群組選取器，將受監控資源限制在特定群組中。如要瞭解用於定義群組成員資格的選取器，請參閱「群組定義的資源選取器」。
{ "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> | monitoring.regex.full_match '(' <RE2-string> ')') {OR project '=' (<number> | <string> | monitoring.regex.full_match '(' <RE2-string> ')')}
如果專案選取器有多個比較項目，請將整個選取器括在括號中，以提高可讀性。例如：
(project=12345 OR project="my-project-id" OR monitoring.regex.full_match("^6789.*") OR monitoring.regex.full_match("some-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。下列篩選器選取器會選取 Spot 執行個體：
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")