Panduan ini menjelaskan cara mengonfigurasi filter saat Anda menggunakan Monitoring API. Anda menggunakan filter untuk menentukan resource yang dipantau, jenis metrik, dan deret waktu.
Sebelum memulai
Jika Anda belum terbiasa dengan metrik, deret waktu, dan resource yang dipantau, lihat Metrik, deret waktu, dan resource.
Jika Anda belum memahami label, lihat Label untuk mengetahui pengantar.
Menggunakan filter
Anda dapat menggunakan filter di Monitoring API untuk melakukan hal berikut:
- Pilih data deret waktu tertentu yang ditampilkan dari permintaan API
list
. Filter dapat memilih deret waktu berdasarkan properti resource yang dipantau dan properti metrik data. Untuk mengetahui informasi dan contoh selengkapnya, lihat Mengambil data deret waktu.
Mencantumkan jenis metrik tertentu. Untuk mengetahui informasi dan contoh selengkapnya, lihat Mencantumkan deskripsi metrik.
Mencantumkan jenis resource yang dimonitor tertentu. Untuk mengetahui informasi dan contoh selengkapnya, lihat Mencantumkan deskripsi resource yang dipantau.
Pemilih filter
Filter terdiri dari minimal satu pemilih, yang merupakan kata kunci filter. Contoh berikut menggambarkan berbagai pemilih:
-
resource
: Mencocokkan resource yang dimonitor dari jenis tertentu atau yang memiliki nilai label tertentu.-
Filter berikut cocok dengan semua resource yang dipantau yang merupakan instance virtual machine (VM) Compute Engine:
resource.type = "gce_instance"
-
-
metric
: Mencocokkan jenis metrik atau deret waktu tertentu dengan dengan label tertentu yang cocok dengan nilai tertentu.-
Filter berikut cocok dengan jenis metrik tertentu:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
-
Filter berikut cocok dengan deret waktu dengan label bernama
instance_name
, yang nilainya diawali dengangke-hipster
ataugke-nginx
:metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")
-
Tabel berikut menunjukkan pemilih yang diizinkan dalam filter berdasarkan panggilan Monitoring API:
Tujuan filter | Pemilih resource |
Pemilih metric |
---|---|---|
Mencantumkan deret waktu | ya | ya * |
Membuat daftar deskriptor metrik | ya | |
Mencantumkan deskriptor resource yang dipantau | ya |
Bagian berikut menunjukkan contoh penggunaan umum filter pemantauan. Lihat Sintaksis filter untuk mengetahui pembahasan lengkap tentang objek dan operator filter yang tersedia.
Mengambil data deret waktu
Metode:
projects.timeSeries.list
Filter objek:
project
, resource.type
, resource.labels.[KEY]
, metric.type
,
metric.labels.[KEY]
Deret waktu adalah daftar titik data berstempel waktu dari jenis metrik dari resource yang dipantau tertentu. Untuk mengetahui detailnya, lihat Model metrik. Jenis metrik ditentukan oleh deskriptor metrik, dan resource yang dimonitor ditentukan oleh deskriptor resource yang dimonitor.
Filter yang ditentukan ke metode timeSeries.list
harus menyertakan pemilih
metric
, dan pemilih tersebut harus menentukan tepat satu jenis metrik:
- Untuk menampilkan semua deret waktu untuk jenis metrik tertentu:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Untuk menampilkan semua deret waktu dari instance Compute Engine tertentu, gunakan filter berikut:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = "my-instance-name"
Menampilkan semua deret waktu dari instance Compute Engine yang namanya diawali dengan
frontend-
, gunakan filter berikut:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = starts_with("frontend-")
Menampilkan semua deret waktu dari instance Compute Engine yang namanya diawali dengan
gke-hipster
ataugke-nginx
, gunakan filter berikut:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
Mencantumkan deskriptor metrik
Metode:
projects.metricDescriptors.list
Filter objek: project
, metric.type
Gunakan filter untuk membatasi deskriptor metrik yang Anda ambil.
Misalnya, untuk hanya menampilkan deskriptor metrik Compute Engine, gunakan filter berikut:
metric.type = starts_with("compute.googleapis.com")
Lihat Daftar metrik untuk mengetahui daftar lengkap jenis metrik yang tersedia. Untuk mengetahui ringkasan cara penamaan metrik, lihat Konvensi penamaan metrik.
Mencantumkan deskripsi resource yang dipantau
Metode:
projects.monitoredResourceDescriptors.list
Filter objek: resource.type
Gunakan filter untuk membatasi deskriptor resource yang dipantau yang Anda ambil.
Misalnya, untuk mengambil hanya deskriptor resource yang dipantau Pub/Sub, gunakan filter berikut:
resource.type = starts_with("pubsub")
Lihat Daftar resource yang dimonitor untuk mengetahui daftar lengkap jenis resource yang dimonitor yang ditentukan oleh Monitoring.
Contoh
Dalam contoh pemfilteran, kita menggunakan deskriptor metrik, deskriptor resource yang dipantau, dan instance virtual machine berikut, yang disederhanakan untuk ilustrasi:
# 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" }
Contoh pengambilan metrik
Untuk meminta penggunaan bandwidth baca disk untuk semua instance dan semua perangkat, tentukan filter sebagai berikut. Filter ini menampilkan, untuk setiap instance, deret waktu terpisah yang melaporkan bandwidth baca untuk setiap perangkat:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
Untuk menyempurnakan permintaan guna membuat kueri bandwidth baca hanya untuk perangkat disk yang dikenal sebagai "log_partition" di setiap instance, tentukan filter sebagai berikut. Filter ini menampilkan, untuk setiap instance, paling banyak satu deret waktu, bergantung pada apakah perangkat dengan nama tersebut ada di instance tersebut:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND metric.labels.device_name = "log_partition"
Untuk membatasi permintaan ke satu instance, tentukan instance tersebut:
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"
Referensi: sintaksis filter
Untuk mengetahui ringkasan filter dengan contoh, lihat Menggunakan filter.
Filter pemantauan adalah string yang terdiri dari hingga dua jenis pemilih:
<monitoring_filter> ::= <resource_selector> AND <metric_selector>
Filter cocok dengan item jika semua pemilih yang disertakan cocok dengan item.
Seperti yang dijelaskan di bagian berikut, beberapa pemilih dapat memiliki beberapa
perbandingan yang digabungkan dengan AND
atau OR
. Urutan pemilih dalam
filter tidak berpengaruh, tetapi perbandingan untuk pemilih yang berbeda tidak boleh
dicampur.
Bergantung pada tujuan filter, pemilih tertentu mungkin diperlukan, opsional, atau dilarang. Misalnya, filter yang digunakan untuk mencantumkan deret waktu harus berisi pemilih metrik.
Perbandingan
Filter dan pemilihnya dibuat dari perbandingan. Setiap perbandingan memiliki format berikut:
-
[OBJECT]: memilih nilai yang akan diuji; salah satu dari berikut ini:
metric.type metric.labels.[KEY] resource.type resource.labels.[KEY]
[KEY] adalah nama, seperti
zone
atauinstance_id
.[KEYSTRING] dapat berupa nama, tetapi jika berisi karakter khusus, maka harus diapit dengan tanda kutip (
"
). -
[OPERATOR]: operator perbandingan; salah satu dari berikut ini:
= # equality (case-sensitive) > < >= <= # numeric ordering != # not equal : # "has" substring match and test for key (case-sensitive)
-
[VALUE]: nilai literal atau panggilan fungsi bawaan; salah satu dari berikut:
<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>)
Kecuali saat digunakan dalam metode
timeSeries.list
, filterhas_substring
menggunakan argumen kedua opsional, yang menentukan apakah kecocokan mengabaikan huruf besar/kecil atau tidak. Nilai defaultnya adalahfalse
, sehingga kecocokan default peka huruf besar/kecil:- Peka huruf besar/kecil:
display_name=has_substring("Demo")
- Peka huruf besar/kecil:
display_name=has_substring("Demo", false)
- Tidak peka huruf besar/kecil:
display_name=has_substring("Demo", true)
Jika digunakan dalam metode
timeSeries.list
, hanya formulirhas_substring(<string>)
yang didukung.Filter
monitoring.regex.full_match
menggunakan string ekspresi reguler dalam sintaksis RE2. - Peka huruf besar/kecil:
Anda dapat menggunakan operator berikut untuk mengelompokkan atau mengubah perbandingan. OR
memiliki
prioritas lebih tinggi daripada AND
. Operator harus ditulis dalam huruf besar:
(...) # grouping comparisons AND # conjunction (optional but recommended) OR # disjunction
Operator AND
dapat dihilangkan di antara operator, tetapi akan lebih jelas dan tidak rentan terhadap kesalahan jika disertakan.
Perbandingan x = one_of("a", "b", "c")
setara dengan berikut ini:
(x = "a" OR x = "b" OR x = "c")
Pemilih filter
Gunakan pemilih untuk membatasi pilihan filter ke item tertentu.
Di bagian berikut, tanda kurung digunakan untuk menunjukkan pengulangan. Misalnya,
notasi <x> {OR <y>}
berarti Anda dapat menulis salah satu dari
berikut:
<x> <x> OR <y> <x> OR <y> OR <y> <x> OR <y> OR <y> OR <y> ...
Pemilih aset
Pemilih resource membatasi pilihan filter ke resource—atau item yang terkait dengan resource—yang memiliki jenis resource atau nilai label tertentu:
<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>}
Jika Anda menggunakan lebih dari satu <r_label_comparison>
dalam pemilih, sertakan semuanya dalam tanda kurung agar lebih mudah dibaca.
Pemilih metrik
Pemilih metrik menentukan metrik atau deskriptor metrik tertentu dengan membatasi
jenis metrik dan label metrik. Saat digunakan dengan metode
projects.timeSeries.list
,
pemilih metrik harus menentukan satu jenis metrik:
<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>}
Misalnya, filter berikut dapat digunakan untuk mengambil deret waktu untuk instance database tertentu:
metric.type = "cloudsql.googleapis.com/database/state" AND (metric.labels.resource_type = "instance" AND metric.labels.resource_id = "abc-123456")