Filter pemantauan

Panduan ini menjelaskan cara mengonfigurasi filter saat Anda menggunakan Monitoring API. Anda menggunakan filter untuk menentukan resource yang dimonitor, jenis metrik, definisi grup , , dan deret waktu.

Anda juga dapat menggunakan filter untuk mengonfigurasi kebijakan pemberitahuan yang memantau proses yang berjalan di sistem Anda. Untuk mengetahui informasi tentang filter tersebut, lihat Filter kondisi proses.

Sebelum memulai

Jika Anda belum terbiasa dengan metrik, deret waktu, dan resource yang dimonitor, lihat Metrik, deret waktu, dan resource.

Jika Anda belum terbiasa dengan label, lihat Label untuk 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 project, grup , properti resource yang dimonitor , dan properti metrik. Untuk mengetahui informasi dan contoh selengkapnya, baca artikel Mengambil data deret waktu.

  • Tetapkan resource ke Group berdasarkan properti resource dan project yang mencakup resource tersebut. Untuk informasi dan contoh selengkapnya, lihat Menentukan keanggotaan grup.

  • Pilih resource dalam grup berdasarkan properti resource dan project tempat resource tersebut berada. Untuk mengetahui informasi dan contoh selengkapnya, lihat Membuat daftar anggota grup.

  • Cantumkan jenis metrik tertentu. Untuk mengetahui informasi dan contoh selengkapnya, lihat Mencantumkan deskripsi metrik.

  • Mencantumkan jenis resource tertentu yang dimonitor. Untuk informasi dan contoh selengkapnya, lihat Mencantumkan deskripsi resource yang dimonitor.

Filter pemilih

Filter terdiri dari setidaknya satu pemilih, yang merupakan kata kunci filter. Contoh berikut menggambarkan pemilih yang berbeda:

  • project: Mencocokkan saat metrik project yang ditentukan terlihat oleh project pencakupan dari cakupan metrik yang disebutkan dalam parameter name.

    Gunakan pemilih project saat project Google Cloud dapat melihat metrik beberapa project Google Cloud atau akun AWS dan Anda hanya menginginkan metrik untuk satu project. Misalnya, jika cakupan metrik untuk Project-A menyertakan Project-B, kecocokan akan terjadi jika name memiliki nilai Project-A dan Anda menggunakan filter berikut:

    project = "Project-B"

  • group: Mencocokkan resource yang termasuk dalam satu Group.

    Filter berikut cocok dengan grup dengan ID group-id:

    group.id = "group-id"

  • resource: Mencocokkan resource yang dimonitor dari jenis tertentu atau memiliki nilai label tertentu.

    • Filter berikut cocok dengan semua resource yang dimonitor yang merupakan instance virtual machine (VM) Compute Engine:

      resource.type = "gce_instance"

    • Filter berikut cocok dengan semua resource yang zonanya diawali dengan europe-:

      resource.labels.zone = starts_with("europe-")

  • metric: Mencocokkan jenis metrik atau deret waktu tertentu 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 mencocokkan deret waktu dengan label bernama instance_name, yang nilainya diawali dengan gke-hipster atau gke-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 project Pemilih group Pemilih resource Pemilih metric
Menentukan grup ya ya*
Membuat daftar anggota grup ya ya
Mencantumkan deret waktu ya ya ya ya †
Mencantumkan deskriptor metrik ya ya
Membuat daftar deskriptor resource yang dipantau ya
* Pemilih resource memiliki opsi tambahan saat digunakan untuk menentukan keanggotaan grup.
† Saat mencantumkan deret waktu, Anda harus menentukan dengan tepat satu jenis metrik.

Bagian berikut menunjukkan contoh penggunaan umum filter pemantauan. Lihat Sintaksis filter untuk mengetahui diskusi lengkap tentang objek dan operator filter yang tersedia.

Mengambil data deret waktu

Metode: projects.timeSeries.list
Filter objek: project, group.id, resource.type, resource.labels.[KEY], metric.type, metric.labels.[KEY]

Deret waktu adalah daftar titik data yang diberi stempel waktu suatu jenis metrik dari resource tertentu yang dimonitor. Untuk mengetahui detailnya, lihat Model metrik. Jenis metrik ditetapkan oleh deskripsi metrik, dan resource yang dimonitor ditetapkan oleh deskripsi resource yang dimonitor.

Filter yang ditentukan ke metode timeSeries.list harus menyertakan pemilih metric, dan pemilih tersebut harus menentukan dengan 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 untuk grup tertentu. Pemilih group hanya berfungsi dengan data deret waktu yang selaras; lihat Pemilih grup untuk mengetahui informasi selengkapnya:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND
group.id = "2468013579"

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

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

  • Tampilkan semua deret waktu dari instance Compute Engine yang namanya diawali dengan gke-hipster atau gke-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).*")

Menentukan keanggotaan grup

Metode: projects.groups
Filter objek: project, resource.type, resource.labels.key, metadata.system_labels.[KEY], metadata.user_labels.[KEY]

Grup dapat berisi berapa pun resource, seperti yang ditentukan oleh filter. Keanggotaan grup bersifat dinamis; lebih banyak atau lebih sedikit resource mungkin cocok dengan filter setiap kali filter dievaluasi. Parameter name dalam objek Group menentukan grup dan project pencakupan dari cakupan metrik]metrics-scope- gaya. Jika pemilih project digunakan di filter, pemilih tersebut harus menentukan project yang metriknya terlihat oleh project pencakupan.

  • Untuk menampilkan daftar semua instance virtual machine (VM) Compute Engine di Eropa, gunakan filter berikut: 
    resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")

Anggota grup listingan

Metode: projects.groups.members.list
Filter objek: project, resource.type, resource.labels.[KEY]

Gunakan filter untuk membatasi anggota grup yang Anda ambil. Parameter name menentukan project pencakupan dari cakupan metrik dan grup yang ditentukan dalam project tersebut. Jika pemilih project digunakan dalam filter, pemilih harus menentukan project yang metriknya terlihat oleh project pencakupan.

  • Untuk menampilkan daftar semua resource topik Pub/Sub yang termasuk dalam project my-project, gunakan filter berikut: 
    project = "my-project" AND resource.type = "pubsub_topic"

Mencantumkan deskriptor metrik

Metode: projects.metricDescriptors.list
Filter objek: project, metric.type

Gunakan filter untuk membatasi deskripsi metrik yang Anda ambil:

  • Untuk menampilkan hanya deskripsi 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 ringkasan tentang cara menamai metrik, lihat Konvensi penamaan metrik.

Mencantumkan deskriptor resource yang dipantau

Metode: projects.monitoredResourceDescriptors.list
Filter objek: resource.type

Gunakan filter untuk membatasi deskripsi resource yang dipantau mana yang Anda ambil:

  • Untuk mengambil hanya deskripsi resource yang dimonitor 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, kami menggunakan deskriptor metrik, deskriptor resource yang dimonitor, dan instance virtual machine, yang disederhanakan sebagai 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 pembacaan disk untuk semua instance dan semua perangkat, tentukan filter sebagai berikut. Filter ini menampilkan, untuk setiap instance, deret waktu terpisah yang melaporkan bandwidth operasi baca untuk setiap perangkat:

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

Guna menyaring permintaan untuk membuat kueri bandwidth operasi baca hanya untuk perangkat disk yang dikenal sebagai "log_partition" di setiap instance, tentukan filter sebagai berikut. Filter ini menampilkan maksimal satu deret waktu untuk setiap instance, bergantung pada apakah perangkat dengan nama tersebut ada di instance tersebut atau tidak:

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"

Pemfilteran dengan grup

Contoh berikut menggambarkan penggunaan pemilih grup dalam filter untuk membatasi resource yang dimonitor hanya untuk resource dalam grup tertentu. Lihat Pemilih resource untuk definisi grup guna mengetahui informasi tentang pemilih yang digunakan untuk menentukan keanggotaan grup.

{ "name": "projects/my-test-project/groups/024681012",
  "display_name": "My Redis Cluster",
  "filter": "metadata.user_labels.role=redis" }

Pada panggilan ke metode projects.timeSeries.list, filter berikut meminta penggunaan bandwidth pembacaan disk untuk semua instance Compute Engine dalam grup tertentu. Grup harus ditentukan dalam project pencakupan cakupan metrik yang ditentukan dalam parameter name metode:

resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

Referensi: sintaksis filter

Untuk ringkasan filter dengan contoh, lihat Menggunakan filter.

Filter pemantauan adalah string yang terdiri hingga empat jenis pemilih:

    <monitoring_filter> ::=  <project_selector> AND
                             <group_selector> AND 
                             <resource_selector> AND
                             <metric_selector>

Filter akan 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 oleh AND atau OR. Urutan pemilih dalam filter tidak menjadi masalah, 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. Namun, filter yang menentukan resource dalam grup tidak dapat berisi pemilih metrik, karena grup tidak berisi jenis metrik atau deret waktu.

Perbandingan

Filter dan pemilihnya dibuat dari perbandingan. Setiap perbandingan memiliki bentuk berikut:

  • [object]: memilih nilai yang akan diuji; salah satu dari berikut ini:

    project
group.id
metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]
metadata.system_labels.[KEY]
metadata.user_labels.[KEYSTRING]

    [KEY] adalah nama, seperti zone atau instance_id.

    [KEYSTRING] dapat berupa nama, tetapi jika berisi karakter khusus, maka harus dikutip 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 ini:

    <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 jika digunakan dalam metode timeSeries.list, filter has_substring menggunakan argumen kedua opsional, yang menentukan apakah pencocokan mengabaikan huruf besar/kecil atau tidak. Nilai defaultnya adalah false, sehingga pencocokan 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 bentuk has_substring(<string>) yang didukung.

    Filter monitoring.regex.full_match mengambil string ekspresi reguler dalam sintaksis RE2.

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 terlalu rentan terhadap error saat menyertakannya.

Perbandingan x = one_of("a", "b", "c") setara dengan perbandingan berikut:

(x = "a" OR x = "b" OR x = "c")
Hanya dalam definisi grup, Anda dapat menggunakan operator negasi unary, NOT, sebelum perbandingan, tetapi tidak dengan operator ada (:) atau sebelum ekspresi yang diberi tanda kurung:

NOT          # negates the following comparison

Filter pemilih

Gunakan pemilih untuk membatasi pilihan filter ke item tertentu. Di bagian berikut, tanda kurung kurawal digunakan untuk menunjukkan pengulangan. Misalnya, notasi <x> {OR <y>} berarti Anda dapat menulis salah satu dari hal berikut:

<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...

Pemilih project

Pemilih project membatasi pemilihan filter pada item yang termasuk dalam satu project atau salah satu dari kumpulan project. Setiap project dapat ditentukan berdasarkan ID atau angkanya:

<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}

Jika pemilih project Anda memiliki lebih dari satu perbandingan, apit seluruh pemilih dalam tanda kurung agar lebih mudah dibaca. Contoh:

(project=12345 OR project="my-project-id") AND resource.type="gce_instance"

Pemilih grup

Pemilih grup membatasi pemilihan filter untuk item yang termasuk dalam grup tunggal:

<group_selector> ::= group.id '=' <string>

Misalnya, filter berikut dapat digunakan untuk mengambil deret waktu dari setiap instance VM dalam grup:

group.id = 12345 AND
resource.type = "gce_instance" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

Pemilih grup hanya diizinkan dalam filter yang diteruskan ke metode projects.timeSeries.list. Selain itu, pemilihan grup memerlukan data yang diselaraskan; yaitu, panggilan projects.timeSeries.list harus menyertakan nilai untuk kolom perSeriesAligner dan alignmentPeriod. Hal ini karena keanggotaan grup itu sendiri adalah semacam deret waktu yang harus digabungkan dengan data metrik, dan menyediakan parameter penyelarasan memberi Anda kontrol atas bagaimana penggabungan tersebut terjadi. Untuk informasi selengkapnya tentang parameter penyelarasan, lihat Menggabungkan data.

Pemilih resource

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, apit semuanya dalam tanda kurung agar lebih mudah dibaca. Misalnya, filter berikut dapat digunakan untuk menentukan grup yang mencakup semua instance VM Compute Engine di AS dan Eropa: 

resource.type = "gce_instance" AND
(resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))

Pemilih resource untuk definisi grup

Pemilih resource yang digunakan untuk menentukan ekstensi penggunaan keanggotaan grup ke sintaksis <resource_selector>:

  • Anda menyertakan filter berdasarkan nilai label sistem metadata, metadata.system_labels.[KEY], dan label pengguna metadata, metadata.user_labels.[KEYSTRING]. Sebaiknya kutip kunci untuk metadata.user_labels karena dapat berisi karakter khusus seperti tanda hubung.

    Jika pemilih berisi filter metadata dan filter resource, Anda harus menggabungkannya dengan AND; Anda tidak dapat menggunakan OR. Misalnya, diagram dengan pemilih berikut menampilkan pemakaian CPU untuk semua instance VM dengan jenis mesin e2-medium atau e2-micro:

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

  • Anda dapat menggunakan operator tidak sama dengan (!=) untuk membandingkan jenis resource, label resource, dan metadata. Operator dapat digunakan saat membandingkan string, angka, Boolean, atau fungsi substring. Misalnya, resource.type!=starts_with("gce") bernilai benar jika jenis resource tidak diawali dengan "gce".

  • Anda dapat menggunakan operator NOT tunggal sebelum perbandingan resource. Misalnya, NOT resource.labels.zone="europe" bernilai benar jika zona resource tidak menyertakan "europe". Anda tidak dapat menggunakan NOT sebelum operator ada (:) atau ekspresi yang diberi tanda kurung.

  • Anda dapat menggunakan operator "exists" (:) untuk menguji keberadaan kunci. Misalnya, perbandingan resource.labels:zone bernilai benar jika kunci label zone ada dalam resource.

Misalnya, salah satu kunci metadata resource platform untuk instance VM adalah spot_instance. Pemilih filter berikut memilih instance yang merupakan instance spot:

resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true

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