Membuat dan mengelola variabel serta filter yang disematkan

Filter dan variabel yang disematkan di dasbor kustom di Cloud Monitoring memungkinkan Anda mengubah data yang ditampilkan di seluruh dasbor secara dinamis dari toolbar tanpa mengedit widget satu per satu. Filter yang disematkan berlaku untuk semua widget yang mendukung label filter, sedangkan variabel berlaku untuk widget tertentu guna mengubah kuerinya atau mengontrol visibilitasnya.

Dokumen ini menjelaskan cara mengonfigurasi filter dan variabel yang disematkan di konsolGoogle Cloud . Untuk mengonfigurasinya menggunakan Cloud Monitoring API, lihat Membuat dan mengelola dasbor menggunakan API: Filter dasbor. Untuk menerapkan filter atau pengelompokan hanya untuk sesi saat ini, lihat Menambahkan filter sementara ke dasbor kustom.

Tentang filter yang disematkan

Filter yang disematkan berisi label, satu atau beberapa nilai default, dan daftar semua nilai yang memungkinkan. Daftar semua kemungkinan nilai diperoleh secara dinamis dari data deret waktu yang ditampilkan di dasbor Anda.

Anda tidak menerapkan filter yang disematkan ke setiap widget. Sebagai gantinya, aturan berikut digunakan untuk menentukan apakah filter yang disematkan dapat mengubah data yang ditampilkan oleh widget:

  • Jika widget menampilkan data yang menyertakan kunci label yang ditentukan oleh filter yang disematkan dan jika widget tidak menentukan nilai untuk kunci label tersebut, filter yang disematkan dapat mengubah data yang ditampilkan.

    Misalnya, Anda menambahkan filter yang disematkan cluster_name: mycluster. Kemudian, diagram akan otomatis menampilkan deret waktu yang memiliki label cluster_name dengan nilai mycluster. Demikian pula, kueri pada widget panel log Anda diubah menjadi resource.labels."cluster_name"="mycluster", dan diagram Anda secara otomatis hanya menampilkan deret waktu yang menyertakan label di filter yang disematkan.

  • Filter yang disematkan akan diabaikan oleh widget jika widget menyertakan filter untuk kunci label yang sama, atau jika data yang ditampilkan oleh widget tidak berisi kunci label yang ditentukan dalam filter yang disematkan.

Di API, filter yang disematkan ditentukan oleh struktur DashboardFilter. Misalnya, struktur berikut menentukan filter yang disematkan. Deret waktu yang memiliki label zone dengan nilai us-central1-c cocok dengan filter yang disematkan.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL"
},

Tentang variabel

Serupa dengan filter yang disematkan, variabel memiliki nama dan jenis, serta satu atau beberapa nilai default. Namun, tidak seperti filter yang disematkan yang selalu berbasis label, variabel tidak harus bergantung pada label.

Variabel diterapkan ke widget tertentu dengan mengubah kueri yang ada di widget tersebut.

Di toolbar dasbor, nama variabel diawali dengan tanda dolar $. Jika Anda juga melihat ikon Terlihat, berarti variabel tersebut mengontrol visibilitas setidaknya satu widget.

Variabel buatan pengguna dapat berbasis label atau hanya memiliki nilai:

  • Variabel berbasis label seperti filter yang disematkan. Variabel ini berisi kunci label, satu atau beberapa nilai label default, dan daftar semua kemungkinan nilai label. Daftar semua kemungkinan nilai diperoleh secara dinamis dari data deret waktu yang ditampilkan di dasbor Anda.

  • Variabel khusus nilai berisi satu atau beberapa nilai default, dan dapat mencantumkan semua nilai yang mungkin. Jika Anda tidak menentukan nilai default, operator karakter pengganti, (*), akan dipilih untuk nilai default. Untuk menentukan kumpulan semua nilai yang mungkin, Anda dapat memberikan array nilai atau menulis kueri SQL.

    Ada tiga jenis variabel khusus nilai: Custom, Text Input, dan Kueri SQL.

    • Kustom: Gunakan jika Anda ingin menghitung daftar semua nilai yang mungkin dan juga menetapkan satu atau beberapa nilai default. Misalnya, Anda dapat menetapkan daftar semua nilai yang mungkin ke prod, staging, dev, dan menetapkan nilai default ke prod.

    • Input Teks: Gunakan jika Anda tidak mengetahui semua kemungkinan nilai. Saat membuat variabel ini, Anda dapat menentukan satu atau beberapa nilai. Namun, opsi menu memungkinkan Anda menambahkan nilai baru yang berlaku untuk sesi saat ini.

    • Kueri SQL: Gunakan jika Anda ingin membuat daftar nilai yang mungkin menggunakan kueri SQL. Variabel ini dimaksudkan untuk diterapkan ke diagram yang dibuat menggunakan Observability Analytics.

      Untuk variabel ini, pastikan hasil kueri adalah tabel dengan satu kolom, jenis data kolom tersebut adalah string, dan setiap baris dalam tabel berisi nilai string yang unik:

      SELECT log_name
FROM `VIEW`
GROUP BY log_name

      Kueri SQL tidak dapat bergantung pada variabel.

Ada satu variabel yang ditentukan sistem, @__project_id. Anda hanya dapat menggunakan variabel ini dalam klausa FROM untuk kueri SQL. Untuk mempelajari cara menerapkan variabel ini ke kueri, lihat Diagram dengan kueri SQL.

Untuk menerapkan variabel ke widget, Anda dapat memperbarui kueri yang dikeluarkan oleh widget atau memperbarui visibilitas widget. Anda dapat mengedit widget kapan saja untuk memperbarui kuerinya. Namun, untuk variabel berbasis label dan beberapa jenis widget, Anda dapat memperbarui kueri dengan membuat pilihan menu. Untuk mengontrol visibilitas, Anda harus mengedit widget. Untuk informasi selengkapnya, lihat bagian berikut dalam dokumen ini:

Di API, variabel ditentukan oleh struktur DashboardFilter. Misalnya, struktur berikut menentukan variabel my_zone_variable yang beroperasi pada label resource zone. Deret waktu yang memiliki label zone dengan nilai us-central1-c cocok dengan variabel.

{
   "labelKey": "zone",
   "stringValue": "us-central1-c",
   "templateVariable": "my_zone_variable",
   "valueType": "STRING",
   "filterType": "RESOURCE_LABEL",
},

Sebelum memulai

Selesaikan langkah-langkah berikut untuk project Google Cloud tempat Anda ingin mengonfigurasi filter dan variabel yang disematkan:

Membuat dan menyematkan filter

Untuk membuat dan menyematkan filter yang berlaku untuk semua widget dasbor yang mendukung filter, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman  Dashboards:

    Buka Dashboards

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
  3. Pilih dasbor, buka toolbar dasbor, lalu klik Settings.
  4. Di bagian Filter, klik Add a filter.
  5. Klik Label, lalu pilih label. Misalnya, Anda dapat memilih zone.
  6. Untuk mengizinkan pengguna memilih beberapa nilai dari menu nilai filter, pilih Multi-pilihan. Jika Pilih beberapa tidak diaktifkan, pengguna hanya dapat memilih satu opsi dari menu nilai.

  7. Klik Nilai default, lalu pilih nilai default, atau beberapa nilai, untuk label. Untuk mencocokkan semua nilai, pilih *.

    Setelah dibuat, filter akan ditambahkan ke toolbar dasbor. Untuk mengubah nilai filter untuk sementara, pilih filter, lalu buat pilihan dari menu.

  8. Klik Selesai, lalu Terapkan.

  9. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

Membuat variabel

Untuk membuat variabel yang berlaku untuk widget dasbor tertentu, lakukan tindakan berikut:

  1. Di konsol Google Cloud , buka halaman  Dashboards:

    Buka Dashboards

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
  3. Pilih dasbor, buka toolbar dasbor, lalu klik Settings.
  4. Di bagian Variables, klik Add a variable.

  5. Pilih jenis variabel, lalu lengkapi dialog.

    Untuk membuat variabel berbasis label, pilih Label. Gunakan opsi ini jika Anda menginginkan variabel yang memiliki kunci label dan nilai label, serta dapat digunakan seperti filter yang disematkan. Daftar semua kemungkinan nilai diperoleh secara dinamis dari data deret waktu yang ditampilkan di dasbor Anda. Menu Apply to charts memungkinkan Anda memilih widget yang kuerinya akan diubah oleh variabel. Anda juga dapat memperbarui kueri dengan mengedit widget.

    Untuk variabel khusus nilai, Anda memiliki opsi berikut:

    • SQL: Gunakan opsi ini jika Anda ingin hasil kueri SQL menghasilkan daftar semua nilai yang mungkin.

      Masukkan satu atau beberapa nilai default, dan masukkan kueri SQL yang menghasilkan daftar semua nilai yang memungkinkan. Pastikan hasil kueri adalah tabel dengan satu kolom, jenis data kolom tersebut adalah string, dan setiap baris dalam tabel berisi nilai string yang unik.

    • Kustom: Gunakan opsi ini jika Anda ingin menentukan daftar nilai yang mungkin dan juga nilai default. Misalnya, Anda dapat menetapkan kolom Nilai ke prod, staging, dev, dan menetapkan Nilai default ke prod.

    • Input Teks: Gunakan opsi ini jika Anda ingin menentukan daftar nilai yang diterapkan sebagai default.

  6. Klik Selesai, lalu Terapkan.

  7. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

    Monitoring akan menambahkan variabel ke toolbar dasbor. Nama di toolbar adalah tanda dolar $ diikuti dengan nama variabel. Toolbar berisi menu yang memungkinkan Anda mengubah nilai variabel.

  8. Opsional: Pindahkan variabel Anda dari toolbar dasbor ke widget dasbor.

    Anda dapat menambahkan widget ke dasbor yang memungkinkan Anda mengubah nilai variabel. Jika Anda melakukan perubahan ini, variabel toolbar akan dihapus. Namun, Anda dapat menempatkan widget yang mengontrol variabel di samping widget yang terpengaruh. Untuk mempelajari cara melakukan perubahan ini, lihat Menambahkan widget untuk mengelola nilai variabel.

  9. Terapkan variabel ke widget. Jika Anda memperbarui kueri widget, maka saat Anda mengubah nilai variabel, kueri akan diubah dan data yang ditampilkan widget akan diubah. Anda juga dapat menggunakan variabel untuk mengontrol apakah widget terlihat. Untuk informasi selengkapnya, lihat bagian berikut dalam dokumen ini:

Menambahkan widget untuk mengelola nilai variabel

Karena variabel berlaku untuk subset widget dasbor, Anda mungkin ingin mengelompokkan kontrol variabel dan widget yang berlaku. Misalnya, Anda dapat membuat grup yang dapat diciutkan atau membuat bagian di dasbor untuk menu variabel dan widget terkait. Strategi ini juga menyederhanakan toolbar, dengan menghapus variabel yang tidak berlaku untuk semua widget.

Untuk mengelola nilai variabel menggunakan widget dasbor, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman  Dashboards:

    Buka Dashboards

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
  3. Dalam dialog Add widget, buka bagian Layout, lalu pilih Variable.

  4. Lengkapi dialog, lalu pilih Simpan.

    Dasbor menampilkan widget yang memungkinkan Anda memilih nilai untuk variabel. Anda dapat memindahkan widget ini ke grup yang dapat diciutkan atau mengubah posisi widget.

  5. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

Menetapkan visibilitas widget

Saat widget mengkueri data, Anda dapat menggunakan variabel untuk mengontrol apakah widget terlihat di dasbor. Misalnya, dasbor berisi widget yang menampilkan data untuk sistem produksi dan kumpulan widget lain yang menampilkan data untuk sistem staging. Saat melakukan proses debug selama pengembangan, Anda mungkin hanya ingin melihat data staging. Dengan mengonfigurasi visibilitas widget dasbor dengan variabel, Anda dapat beralih antara hanya data produksi, hanya data staging, dan semua data.

Semua jenis variabel dapat mengontrol apakah widget terlihat atau tersembunyi.

Untuk mengonfigurasi visibilitas widget, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman  Dashboards:

    Buka Dashboards

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Pilih dasbor.
  3. Buka toolbar widget yang visibilitasnya ingin Anda konfigurasi, lalu klik Edit.
  4. Di panel Display, luaskan Widget visibility.

  5. Pilih variabel dan lengkapi dialog.

  6. Klik Selesai, lalu Terapkan.

  7. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

    Dasbor dimuat ulang. Jika setidaknya satu widget di dasbor disembunyikan karena kontrol visibilitas, dasbor akan menampilkan banner. Untuk melihat semua widget, klik Tampilkan semua widget.

Saat Anda menggunakan variabel untuk mengontrol visibilitas setidaknya satu widget di dasbor, di toolbar, nama variabel akan dianotasi dengan ikon Visible.

Batasan

Batasan berikut berlaku saat mengonfigurasi visibilitas widget:

  • Widget organisasi, seperti grup yang dapat diciutkan, header bagian, dan widget tampilan tunggal, selalu terlihat.

  • Anda dapat menghapus variabel yang direferensikan oleh kontrol visibilitas widget. Tindakan penghapusan variabel juga akan menghapus referensi apa pun ke variabel tersebut.

  • Tidak semua dasbor mendukung pembuatan variabel. Namun, jika dasbor berisi variabel, Anda dapat menggunakan variabel tersebut untuk mengelola visibilitas widget di dasbor.

Memperbarui kueri widget

Bagian ini menjelaskan cara menyertakan variabel dalam kueri yang dikeluarkan widget. Akibatnya, saat Anda mengubah nilai variabel, kueri akan diubah dan data yang ditampilkan widget akan diubah:

  • Untuk diagram yang menggunakan kueri SQL atau PromQL, dan untuk widget panel log, Anda harus mengedit widget dan mengubah kueri. Bagian ini menjelaskan cara melakukan pengeditan tersebut.

  • Untuk diagram yang Anda konfigurasi menggunakan menu atau menggunakan mode filter langsung, Monitoring akan mengedit kueri saat Anda memilih widget menggunakan menu Apply to charts. Sebagai alternatif, Anda dapat mengedit widget, membuka kolom Filter, lalu memilih variabel.

Untuk mempelajari cara memperbarui kueri widget dengan variabel berbasis label atau variabel khusus nilai, lihat bagian berikut:

Membuat filter dan variabel

Konsol

Untuk mengetahui informasi tentang cara menggunakan konsol Google Cloud untuk membuat filter dan variabel yang disematkan, lihat dokumen berikut:

REST

Untuk menentukan filter dan variabel yang disematkan, gunakan struktur data dashboardFilters.

  • Untuk membuat variabel, tetapkan nilai kolom templateVariable ke nama variabel. Hapus kolom ini atau tetapkan nilainya ke string kosong jika Anda ingin membuat filter yang disematkan.
  • Untuk membuat filter yang disematkan atau variabel berbasis label, Anda harus menentukan kolom labelKey. Hapus kolom ini jika Anda menginginkan variabel khusus nilai.

  • Tetapkan nilai default untuk filter atau variabel. Konfigurasi kolom ini menentukan apakah pengguna dapat memilih tepat satu opsi dari menu nilai, atau apakah mereka dapat memilih beberapa nilai.

  • Untuk menetapkan satu nilai default dan membatasi pengguna agar hanya memilih satu opsi di menu nilai, tetapkan kolom valueType sebagai STRING dan tetapkan juga kolom stringValue:

    "valueType": "STRING",
"stringValue": "my-default-value",

  • Untuk menetapkan setidaknya satu nilai default dan mengizinkan pengguna memilih beberapa opsi di menu nilai, tetapkan kolom valueType sebagai STRING_ARRAY dan tetapkan juga kolom stringArrayValue. Dalam contoh berikut, ada tiga nilai default.

    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • Opsional: Untuk menentukan daftar semua nilai yang mungkin untuk variabel khusus nilai, tetapkan kolom stringArray atau kolom timeSeriesQuery. Jika Anda menentukan kueri, kueri tersebut harus berupa kueri analisis.

Misalnya, pertimbangkan objek dashboardFilters berikut:

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

JSON sebelumnya menentukan satu filter yang disematkan dan dua variabel:

  • Filter yang disematkan memiliki kunci label zone, yang ditampilkan di toolbar. Kolom valueType dan stringValue menentukan nilai default tunggal. Untuk mengetahui informasi selengkapnya, lihat halaman referensi API untuk struktur data dashboardFilters.

  • Variabel berbasis label memiliki nama my_label_based_variable, dan kunci labelnya adalah instance_id. Nilai default untuk variabel ini ditetapkan ke ID instance tertentu. Anda juga dapat mengonfigurasi nilai default menggunakan array. Di toolbar, filter ditampilkan dengan nama my_label_based_variable.

  • Variabel khusus nilai diberi nama my_value_only_variable. Entri ini tidak menentukan nilai default, sehingga operator karakter pengganti, (*), akan diterapkan secara otomatis. Selain itu, variabel ini menggunakan kueri SQL untuk membuat daftar kemungkinan nilai untuk variabel.

Perhatikan bahwa objek dashboardFilters tidak mencantumkan widget yang menerapkan variabel. Sebagai gantinya, Anda memperbarui kueri widget agar bergantung pada variabel.

Sintaksis umum untuk mendereferensikan variabel

Untuk semua widget, kecuali yang ditentukan oleh SQL, gunakan sintaksis berikut untuk menerapkan variabel ke kueri:

  • Untuk menerapkan variabel berbasis label dan membuat kunci label serta nilai label di-resolve menjadi ekspresi filter yang valid untuk bahasa kueri, gunakan ${my_label_based_variable}.

  • Untuk menerapkan hanya nilai variabel berbasis label, gunakan ${my_label_based_variable.value}. Perbandingan harus menggunakan ekspresi reguler.

  • Untuk menerapkan hanya nilai dari variabel khusus nilai, gunakan ${my_value_only_variable}. Untuk variabel khusus nilai, jangan sertakan klausa .value. Perbandingan harus menggunakan ekspresi reguler.

Widget panel log

Untuk menerapkan variabel ke widget panel log, perbarui panel kueri. Sintaksis untuk widget ini mengikuti sintaksis yang ditentukan di bagian Sintaksis umum.

Konsol

Misalnya, kueri berikut menggunakan ekspresi reguler untuk membandingkan nilai kolom jsonPayload.message dengan nilai string yang menyertakan nilai variabel berbasis label:

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"

Sebagai contoh lain, pertimbangkan variabel khusus nilai, value_only_severity_variable, dan asumsikan bahwa dalam menu nilai, tiga nilai dipilih: ERROR, INFO, dan NOTICE. Selanjutnya, tambahkan kode berikut ke panel kueri widget panel log Anda:

severity =~ "${value_only_severity_variable}"

Berikut ini ilustrasi formulir yang dirender:

severity =~ "^(ERROR|INFO|NOTICE)$"

REST

Misalnya, JSON berikut menggambarkan cara memperbarui kueri widget panel log dengan variabel berbasis label:

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

Misalnya, kueri berikut menggunakan ekspresi reguler untuk membandingkan nilai kolom jsonPayload.message dengan nilai string yang menyertakan nilai variabel berbasis label:

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
            resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

Sebagai contoh lain, pertimbangkan variabel khusus nilai, value_only_severity_variable, dan asumsikan bahwa tiga nilai dipilih dalam menu: ERROR, INFO, dan NOTICE. Selanjutnya, tambahkan kode berikut ke panel kueri widget panel log Anda:

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

Berikut ini ilustrasi kueri yang dijalankan oleh widget panel log:

severity =~ "^(ERROR|INFO|NOTICE)$"

Jika Anda telah mengonfigurasi kueri untuk panel log, lalu memilih tombol untuk membuka Logs Explorer, variabel akan di-resolve sebelum Logs Explorer dibuka.

Tabel berikut menggambarkan cara variabel contoh diselesaikan oleh panel log. Seperti yang disebutkan sebelumnya, jika hanya nilai variabel yang digunakan, Anda harus menggunakan ekspresi reguler sebagai operator perbandingan:

Sintaksis Nilai
yang Dipilih		 Ekspresi panel log yang diselesaikan
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

Variabel contoh didasarkan pada label resource instance_id.
${my_label_based_variable} * ""
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

Diagram dengan kueri PromQL

Untuk memperbarui diagram yang memiliki kueri PromQL agar bergantung pada variabel berbasis label, ikuti panduan yang tercantum dalam Sintaksis umum.

Konsol

Misalnya, kueri berikut mengandalkan variabel berbasis label, my_label_based_variable, yang di-resolve menjadi ekspresi filter:

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

Anda juga dapat mengubah kueri untuk me-resolve hanya nilai variabel. Contoh berikut menggunakan ekspresi reguler untuk membandingkan nilai kueri berbasis label dengan instance_id:

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${my_label_based_variable.value}"
}

Jika Anda memiliki variabel khusus nilai, hapus klausa .value. Misalnya, untuk memfilter menurut zona menggunakan variabel khusus nilai, kueri akan menyertakan sesuatu seperti berikut:

zone=~"${my_value_only_variable}"

REST

Misalnya, JSON berikut mengilustrasikan kueri yang mengandalkan variabel berbasis label, my_label_based_variable, yang di-resolve menjadi ekspresi filter:

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

Anda juga dapat mengubah kueri untuk me-resolve hanya nilai variabel. Contoh berikut menggunakan ekspresi reguler untuk membandingkan nilai kueri berbasis label dengan instance_id:

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

Jika Anda memiliki variabel khusus nilai, hapus klausa .value. Misalnya, untuk memfilter menurut zona menggunakan variabel khusus nilai, kueri akan menyertakan sesuatu seperti berikut:

zone=~\"${my_value_only_variable}\"

Tabel berikut menggambarkan cara variabel contoh diselesaikan oleh PromQL. Seperti yang disebutkan sebelumnya, jika hanya nilai variabel yang digunakan, Anda harus menggunakan ekspresi reguler sebagai operator perbandingan:

Sintaksis Nilai
yang Dipilih		 Ekspresi PromQL yang diselesaikan
${my_label_based_variable} 12345 instance_id == '12345'

Variabel contoh didasarkan pada label resource instance_id.
${my_label_based_variable} * noop_filter=~".*"
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .+

Diagram dengan kueri SQL

Ada dua tempat yang dapat Anda gunakan untuk menggunakan variabel dalam kueri SQL:

  • Klausa FROM dapat bergantung pada variabel yang ditentukan sistem bernama @__project_id, yang di-resolve ke nilai project yang Anda pilih.

  • Klausa WHERE dapat bergantung pada variabel buatan pengguna.

Mengupdate klausa FROM agar bergantung pada variabel yang ditentukan sistem

Jika Anda membuat template dasbor dan template ini memetakan hasil kueri SQL, ganti project ID dalam kueri Anda dengan variabel @__project_id. Saat Anda menginstal template dalam project, variabel akan otomatis di-resolve ke project ID. Anda tidak perlu mengedit widget secara manual dan memperbarui klausa FROM.

Berikut ini adalah ilustrasi klausa FROM yang bergantung pada variabel yang ditentukan sistem:

FROM `@__project_id.global._Default._Default`

Klausa FROM tidak dapat bergantung pada variabel buatan pengguna.

Memperbarui klausa WHERE agar bergantung pada variabel buatan pengguna

Bagian ini menjelaskan cara memperbarui klausa WHERE widget yang ditentukan SQL agar bergantung pada variabel buatan pengguna. Untuk semua variabel, beri awalan nama variabel dengan tanda "at", misalnya: @variable_name. Untuk variabel berbasis label, tambahkan .value ke nama variabel, @my_label_based_variabe.value.

Untuk kueri SQL, penggantian variabel mengandalkan BigQuery, dan aman dari injeksi SQL. Untuk mengetahui informasi selengkapnya, lihat Menjalankan kueri berparameter.

Konsol

Karena SQL tidak menafsirkan operator karakter pengganti sebagai "nilai apa pun", sebaiknya Anda selalu menggunakan pernyataan IF saat menggunakan variabel dalam kueri SQL. Contoh berikut mengilustrasikan penggunaan untuk variabel khusus nilai yang jenis datanya adalah string:

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Jika opsi menu untuk variabel memungkinkan pengguna memilih beberapa nilai, Anda harus mentransmisikan nilai variabel ke jenis data GoogleSQL menggunakan fungsi CAST. Kueri berikut mengilustrasikan sintaksis ini:

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

Pernyataan IF yang ditampilkan dalam contoh sebelumnya direkomendasikan karena SQL tidak menafsirkan operator karakter pengganti sebagai "nilai apa pun". Oleh karena itu, jika Anda menghilangkan pernyataan IF dan jika Anda memilih operator karakter pengganti, hasil kueri akan berupa tabel kosong. Pada contoh kedua, fungsi UNNEST mengonversi array menjadi tabel.

Untuk menambahkan klausa WHERE dengan format yang benar, lakukan hal berikut:

  1. Edit widget.
  2. Di toolbar, pilih Insert variable filter, lalu pilih variabel yang klausa WHERE-nya ingin Anda perbarui.
  3. Dalam dialog yang terbuka, tinjau kode yang dihasilkan, lalu klik Copy and close.

  4. Tempelkan kode yang disalin ke panel Query dan lakukan pengeditan yang diperlukan.

    Misalnya, Anda membuat variabel bernama LogName yang menghasilkan daftar nama log dan menampilkan hasilnya dalam tabel dengan satu kolom bernama log_name. Selanjutnya, Anda membuat diagram, memilih Sisipkan filter variabel, lalu memilih variabel LogName. Kode berikut akan dibuat:

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    Dalam contoh ini, Anda perlu mengedit kode yang dihasilkan dan mengganti LogName = dengan log_name =, sehingga penggabungan tabel dapat terjadi:

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. Klik Jalankan, lalu Terapkan.

  6. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

REST

Karena SQL tidak menafsirkan operator karakter pengganti sebagai "nilai apa pun", sebaiknya Anda selalu menggunakan pernyataan IF saat menggunakan variabel dalam kueri SQL. Contoh berikut mengilustrasikan penggunaan untuk variabel khusus nilai yang jenis datanya adalah string:

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

Misalnya, berikut ini adalah representasi JSON parsial dari diagram yang menampilkan hasil kueri SQL. Untuk mendukung pemfilteran hasil berdasarkan nama log, klausa WHERE ditambahkan yang mereferensikan variabel bernama LogName:

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

Variabel LogName juga mengeluarkan kueri untuk menentukan daftar kemungkinan nama log:

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

Jika opsi menu untuk variabel memungkinkan pengguna memilih beberapa nilai, Anda harus mentransmisikan nilai variabel ke jenis data GoogleSQL menggunakan fungsi CAST. Kueri berikut mengilustrasikan sintaksis ini:

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

Pernyataan IF yang ditampilkan dalam contoh sebelumnya direkomendasikan karena SQL tidak menafsirkan operator karakter pengganti sebagai "nilai apa pun". Oleh karena itu, jika Anda menghilangkan pernyataan IF dan jika Anda memilih operator karakter pengganti, hasil kueri akan berupa tabel kosong. Pada contoh kedua, fungsi UNNEST mengonversi array menjadi tabel.

Diagram dengan kueri filter Monitoring

Untuk mengupdate diagram yang memiliki kueri dalam bentuk filter Monitoring agar bergantung pada variabel berbasis label, ikuti panduan yang tercantum dalam Sintaksis umum.

Konsol

Jika Anda menggunakan konsol Google Cloud untuk membuat diagram, dan jika Anda menggunakan antarmuka berbasis menu, Anda dapat memperbarui kueri diagram dengan menggunakan kolom Terapkan ke diagram variabel atau dengan mengedit widget dan memilih variabel berbasis label dari menu Filter. Menu Filter mencantumkan semua variabel berbasis label dan semua kunci label.

Untuk memperbarui kueri diagram agar bergantung pada variabel berbasis nilai, lakukan hal berikut:

  1. Edit diagram.
  2. Di panel kueri, klik Add filter dan pilih kunci label. Misalnya, Anda dapat memilih zone.
  3. Di menu Value, pilih variabel khusus nilai Anda.
  4. Klik Terapkan.
  5. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

Misalnya, JSON berikut mengilustrasikan kueri yang mengandalkan variabel berbasis label, my_label_based_variable, yang di-resolve menjadi ekspresi filter:

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

Widget yang menggunakan kueri dalam bentuk filter Monitoring tidak dapat memfilter deret waktu berdasarkan nilai dalam variabel berbasis label; namun, Anda dapat memfilter menurut variabel khusus nilai. Misalnya, kueri berikut menampilkan nilai kolom Filters dari kueri yang memfilter menurut zone, berdasarkan nilai variabel khusus nilai:

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

REST

Misalnya, JSON berikut mengilustrasikan kueri yang mengandalkan variabel berbasis label, my_label_based_variable, yang di-resolve menjadi ekspresi filter:

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
              resource.type=\"gce_instance\"
              ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

Widget yang menggunakan kueri dalam bentuk filter Monitoring tidak dapat memfilter deret waktu berdasarkan nilai dalam variabel berbasis label; namun, Anda dapat memfilter menurut variabel khusus nilai. Misalnya, kueri berikut menampilkan kolom "filter" dari kueri yang memfilter menurut zone, berdasarkan nilai variabel khusus nilai:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

Tabel berikut menggambarkan cara variabel contoh diselesaikan oleh filter Monitoring. Seperti yang disebutkan sebelumnya, jika hanya nilai variabel yang digunakan, Anda harus menggunakan ekspresi reguler sebagai operator perbandingan:

Sintaksis Nilai
yang Dipilih		 Ekspresi filter yang diselesaikan
${my_label_based_variable} 12345 resource.instance_id == "12345"

Variabel contoh didasarkan pada label resource instance_id.
${my_label_based_variable} * Dihilangkan
${my_label_based_variable.value} 12345 Tidak didukung
${my_label_based_variable.value} * Tidak didukung
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

Mengubah filter atau variabel yang disematkan

Untuk mengubah sementara nilai filter atau variabel yang disematkan yang ditampilkan di toolbar dasbor, klik nama filter atau variabel, lalu masukkan nilai atau buat pilihan dari menu.

Jika dasbor Anda berisi tabel yang menampilkan data deret waktu, Anda dapat menambahkan filter sementara atau mengubah filter dan variabel permanen menggunakan tombol Filter dashboard to this value sel. Tombol ini, jika dipilih, akan menerapkan filter sementara baru atau memperbarui nilai untuk filter atau variabel yang ada. Filter dan variabel yang ada akan diperbarui jika kunci label untuk kolom tabel cocok dengan kunci label untuk filter atau variabel.

Untuk mengubah konfigurasi filter yang disematkan atau variabel, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman  Dashboards:

    Buka Dashboards

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
  3. Di toolbar dasbor, klik Settings.
  4. Temukan filter atau variabel yang ingin Anda ubah dan luaskan definisinya.
  5. Setelah Anda menyelesaikan perubahan, klik Terapkan.
  6. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

Menghapus filter atau variabel yang disematkan

Untuk menghapus filter yang disematkan atau variabel, lakukan tindakan berikut:

  1. Di konsol Google Cloud , buka halaman  Dashboards:

    Buka Dashboards

    Jika Anda menggunakan kotak penelusuran untuk menemukan halaman ini, pilih hasil yang subjudulnya adalah Monitoring.

  2. Di toolbar konsol Google Cloud , pilih project Google Cloud Anda. Untuk konfigurasi App Hub, pilih project host atau project pengelolaan App Hub.
  3. Di toolbar dasbor, klik Settings.
  4. Temukan filter atau variabel yang ingin Anda hapus, lalu klik Hapus.
  5. Klik Terapkan.
  6. Untuk menyimpan dasbor yang telah diubah, klik Save di toolbar.

Batasan

  • Filter tingkat dasbor mengandalkan pemfilteran data berdasarkan key-value pair. Filter ini tidak berlaku jika data tidak mendukung key-value pair atau jika data tidak mendukung kunci tertentu. Misalnya, Anda tidak dapat menggunakan filter tingkat dasbor untuk mengubah data yang ditampilkan widget trace.

  • Untuk menerapkan variabel ke widget, Anda harus mengubah kueri widget. Tidak semua widget mendukung modifikasi.

Langkah berikutnya