Membuat dan mengelola dasbor menurut API

Dokumen ini menjelaskan cara membuat dan mengelola dasbor kustom serta widget di dasbor tersebut menggunakan resource Dashboard di Cloud Monitoring API. Contoh di sini menggambarkan cara mengelola dasbor menggunakan curl untuk memanggil API, dan menunjukkan cara menggunakan Google Cloud CLI. Meskipun Anda juga dapat mengelola dasbor kustom melalui konsol Google Cloud, API ini memberi Anda cara terprogram untuk mengelola banyak dasbor secara bersamaan.

Endpoint ini mendukung metode berikut untuk mengelola dan mengonfigurasi dasbor:

Anda dapat memanggil API secara langsung menggunakan utilitas curl atau menggunakan Google Cloud CLI.

Anda tidak dapat mengambil, mengedit, atau menghapus dasbor standar.

Fitur ini hanya didukung untuk project Google Cloud.

Tentang dasbor

Saat membuat dasbor, Anda harus menentukan komponen, atau widget, yang ingin ditampilkan, dan tata letak untuk widget tersebut. Anda juga dapat menambahkan label dan filter ke dasbor. Label dapat membantu Anda menemukan dasbor atau menunjukkan jenis konten di dasbor.

Tata letak dasbor

Tata letak menentukan cara komponen dasbor diurutkan. API ini menyediakan tata letak berikut:

  • GridLayout: membagi ruang yang tersedia menjadi kolom vertikal dengan lebar yang sama dan mengatur kumpulan widget menggunakan strategi baris pertama.

  • MosaicLayout: membagi ruang yang tersedia menjadi petak. Setiap widget dapat menempati satu atau beberapa blok petak.

  • RowLayout: membagi ruang yang tersedia menjadi baris dan mengatur sekumpulan widget secara horizontal di setiap baris.

  • ColumnLayout: membagi ruang yang tersedia menjadi kolom vertikal dan mengatur kumpulan widget secara vertikal di setiap kolom.

Misalnya, berikut ini menunjukkan representasi JSON dasbor di RowLayout dengan tiga widget Text:

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

Widget dasbor

Widget berisi satu komponen dasbor dan konfigurasi cara menampilkan komponen di dasbor. Dasbor dapat memiliki lebih dari satu widget. Ada beberapa jenis objek Widget:

  • Widget XyChart menampilkan data pada sumbu X dan Y.

    Widget ini menampilkan set data yang dapat berupa data deret waktu atau dihasilkan oleh kueri SQL. Widget ini memungkinkan Anda mengaitkan data diagram dengan sumbu Y kiri atau kanan. Jika beberapa jenis metrik dipetakan, Anda dapat menggunakan kedua sumbu Y. Widget XyChart mendukung gaya tampilan berikut:

    • Diagram garis
    • Diagram batang
    • Diagram area bertumpuk
    • Peta panas

  • Widget yang ditampilkan dari satu dimensi, seperti nilai terbaru:

    • PieChart: menampilkan nilai terbaru dari kumpulan deret waktu, dengan setiap deret waktu berkontribusi satu bagian pada lingkaran.

    • Scorecard: menampilkan nilai terbaru dari satu deret waktu, dan bagaimana nilai ini terkait dengan satu atau beberapa nilai minimum.

    • TimeSeriesTable: menampilkan nilai terbaru, atau nilai gabungan, untuk setiap deret waktu. Tabel mendukung penyesuaian. Misalnya, Anda dapat memberi kode warna pada sel dan mengonfigurasi nama kolom serta perataan data.

  • Widget yang menampilkan kebijakan pemberitahuan atau informasi insiden:

    • AlertChart: menampilkan ringkasan kebijakan pemberitahuan satu kondisi. Widget ini menampilkan data sebagai diagram garis, menunjukkan nilai minimum, dan mencantumkan jumlah insiden yang terbuka.

    • IncidentList: menampilkan daftar insiden. Anda dapat mengonfigurasi widget untuk menampilkan insiden untuk kebijakan pemberitahuan tertentu atau untuk jenis resource tertentu.

  • Widget yang menampilkan entri log dan error:

  • Widget teks dan organisasi:

    • CollapsibleGroup: menampilkan kumpulan widget. Anda dapat menciutkan tampilan grup.

    • SingleViewGroup: menampilkan satu widget dalam kumpulan widget. Anda dapat memilih widget yang akan ditampilkan.

    • SectionHeader: membuat pemisah horizontal di dasbor, dan membuat entri dalam tabel konten dasbor.

    • Text: menampilkan konten tekstual, baik sebagai teks mentah maupun string Markdown.

    Untuk menyertakan widget teks dan organisasi di dasbor, dasbor harus memiliki MosaicLayout.

Selain objek ini, Anda juga dapat menambahkan placeholder kosong ke dasbor.

Misalnya, berikut adalah representasi JSON widget XyChart yang sumbu Y kanannya dikonfigurasi:

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Label dasbor

Label dapat membantu Anda mengelola dan mengatur dasbor. Misalnya, Anda dapat menambahkan label bernama prod untuk menunjukkan bahwa dasbor menampilkan data deret waktu dan data log untuk resource produksi Anda. Atau, Anda dapat menambahkan label playbook untuk menunjukkan bahwa dasbor berisi informasi untuk membantu Anda memecahkan masalah kegagalan.

Menambahkan label ke dasbor bersifat opsional.

Misalnya, berikut ini menunjukkan objek Dashboard yang menentukan label bernama playbook.

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

Seperti yang diilustrasikan contoh sebelumnya, kolom labels diterapkan sebagai map, dengan kolom key dan value berupa string. Saat Anda menambahkan label ke dasbor, tetapkan key ke nama label, dan tetapkan kolom value ke string kosong.

Filter dan variabel dasbor

Saat mendesain dasbor, Anda mungkin mengidentifikasi beberapa cara untuk melihat data yang ditampilkan dasbor. Misalnya, dasbor menampilkan data deret waktu untuk instance virtual machine (VM) Anda. Anda mungkin ingin melihat data deret waktu untuk semua VM, dan Anda mungkin hanya ingin melihat data yang ada di zona tertentu. Dalam situasi ini, sebaiknya buat filter yang disematkan atau variabel, lalu tetapkan nilai default filter tersebut ke zona yang paling sering dilihat.

Filter yang disematkan berlaku untuk semua widget dasbor yang mendukung label yang ditentukan dalam filter, kecuali jika widget berisi filter dengan kunci label yang sama. Misalnya, saat diagram menyertakan filter zone = us-central1-a, diagram tersebut akan mengabaikan filter yang disematkan dengan kunci label zone. Demikian pula, filter ini diabaikan oleh diagram yang tidak memiliki label dengan kunci zone.

Variabel mirip dengan filter yang disematkan, tetapi hanya berlaku untuk widget tertentu. Variabel dapat didasarkan pada label, seperti filter yang disematkan, atau hanya dapat memiliki nilai. Variabel khusus nilai berisi satu atau beberapa nilai default, dan daftar semua kemungkinan nilai. Jika Anda tidak menentukan nilai default, nilai default akan ditetapkan ke operator karakter pengganti (*). Untuk menentukan kumpulan semua kemungkinan nilai, Anda dapat memberikan array nilai atau menulis kueri SQL.

Untuk widget yang membuat kueri data, Anda dapat menyertakan variabel dalam kueri widget dan Anda dapat menggunakan variabel untuk mengontrol visibilitas widget. Jika kueri bergantung pada variabel, data yang diminta widget akan berubah saat Anda mengubah nilai variabel. Akibatnya, data yang ditampilkan juga berubah. Saat Anda menggunakan variabel untuk mengontrol visibilitas widget, ikon Visible akan ditampilkan di toolbar. Untuk batasan yang terkait dengan visibilitas, lihat Menetapkan visibilitas widget.

Untuk filter dan variabel yang disematkan, toolbar dasbor menampilkan setiap variabel, beserta menu, yang memungkinkan Anda mengubah nilai variabel untuk sementara. Struktur data yang sama digunakan untuk merepresentasikan filter dan variabel yang disematkan. Untuk membantu Anda membedakan filter dari variabel, di toolbar dasbor, nama variabel diawali dengan tanda dolar $. Untuk informasi selengkapnya, lihat DashboardFilter.

Untuk contoh yang menunjukkan cara mengontrol visibilitas widget menggunakan variabel, lihat Dasbor dengan visibilitas widget yang dikonfigurasi.

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

Membuat filter dan variabel

Konsol

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

API

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 nilai ke string kosong saat 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 juga tetapkan kolom stringArrayValue. Dalam contoh berikut, ada tiga nilai default.
    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

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

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 satu nilai default. Untuk 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, (*), 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 dan nilai label di-resolve menjadi ekspresi filter yang valid untuk bahasa kueri, gunakan ${my_label_based_variable}.

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

  • Untuk hanya menerapkan nilai 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)$"

API

Misalnya, JSON berikut mengilustrasikan 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 di 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 dieksekusi 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 contoh variabel di-resolve oleh panel log. Seperti yang disebutkan sebelumnya, jika hanya nilai variabel yang digunakan, Anda harus menggunakan ekspresi reguler sebagai operator perbandingan:

Sintaks Selected
Value		 Ekspresi panel log yang di-resolve
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

Contoh variabel 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 di 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 hanya me-resolve 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 hal seperti berikut:

zone=~"${my_value_only_variable}"

API

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 hanya me-resolve 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 hal seperti berikut:

zone=~\"${my_value_only_variable}\"

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

Sintaks Selected
Value		 Ekspresi PromQL yang di-resolve
${my_label_based_variable} 12345 instance_id == '12345'

Contoh variabel 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

Jika Anda ingin memperbarui widget yang ditentukan SQL agar bergantung pada variabel, perbarui klausa WHERE untuk mereferensikan nilai variabel. 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 bergantung pada 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 menghapus pernyataan IF dan jika Anda memilih operator karakter pengganti, hasil kueri adalah tabel kosong. Pada contoh kedua, fungsi UNNEST mengonversi array menjadi tabel.

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

  1. Edit widget.
  2. Di toolbar, pilih Sisipkan filter variabel, lalu pilih variabel yang klausa WHERE-nya ingin Anda perbarui.
  3. Dalam dialog yang terbuka, tinjau kode yang dihasilkan, lalu klik Salin dan tutup.

  4. Tempel kode yang disalin ke panel Kueri 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 Simpan di toolbar.

API

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 adalah representasi JSON sebagian 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 nama log yang mungkin:

"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 menghapus pernyataan IF dan jika Anda memilih operator karakter pengganti, hasil kueri adalah tabel kosong. Pada contoh kedua, fungsi UNNEST mengonversi array menjadi tabel.

Diagram dengan kueri MQL

Untuk diagram yang memiliki kueri MQL untuk menggunakan variabel berbasis label, tambahkan pipa, (|), lalu ikuti panduan yang tercantum di Sintaksis umum.

Saat Anda menggunakan antarmuka berbasis menu untuk membuat diagram yang menampilkan data deret waktu, pilihan Anda akan dikonversi menjadi Filter Monitoring

Konsol

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${my_label_based_variable}

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

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~'${my_label_based_variable.value}'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

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

resource.zone=~'${my_value_only_variable}'

API

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

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

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

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

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

resource.zone=~'${my_value_only_variable}'

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

Sintaks Selected
Value		 Ekspresi MQL yang di-resolve
${my_label_based_variable} 12345 filter (resource.instance_id == '12345')

Contoh variabel didasarkan pada label resource instance_id.
${my_label_based_variable} * filter (true)
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

Diagram dengan kueri filter Monitoring

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

Konsol

Jika menggunakan konsol Google Cloud untuk membuat diagram, dan jika menggunakan antarmuka berbasis menu, Anda dapat memperbarui kueri diagram 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 Tambahkan filter, lalu pilih kunci label. Misalnya, Anda dapat memilih zona.
  3. Di menu Value, pilih variabel khusus nilai.
  4. Klik Terapkan.
  5. Untuk menyimpan dasbor yang telah diubah, klik Simpan 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 berdasarkan variabel khusus nilai. Misalnya, kueri berikut menampilkan nilai kolom Filters 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})

API

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; tetapi, Anda dapat memfilter berdasarkan 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 di-resolve oleh filter Monitoring. Seperti yang disebutkan sebelumnya, jika hanya nilai variabel yang digunakan, Anda harus menggunakan ekspresi reguler sebagai operator perbandingan:

Sintaks Selected
Value		 Ekspresi filter yang di-resolve
${my_label_based_variable} 12345 resource.instance_id == "12345"

Contoh variabel 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} * ".*"

Sebelum memulai

Selesaikan langkah-langkah berikut di project Google Cloud tempat Anda ingin membuat atau mengelola dasbor:

  • Select the tab for how you plan to use the samples on this page:

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    Terraform

    Untuk menggunakan contoh Terraform di halaman ini dalam lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Untuk informasi selengkapnya, lihat Menyiapkan ADC untuk lingkungan pengembangan lokal dalam Google Cloud dokumentasi autentikasi.

    REST

    Untuk menggunakan contoh REST API di halaman ini dalam lingkungan pengembangan lokal, gunakan kredensial yang Anda berikan ke gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    Untuk informasi selengkapnya, lihat Mengautentikasi untuk menggunakan REST dalam Google Cloud dokumentasi autentikasi.

Membuat dasbor

Untuk membuat dasbor kustom baru, panggil metode dashboards.create dan berikan tata letak serta widget yang akan ditampilkan di dasbor.

Saat Anda membuat dasbor, API akan otomatis membuat dashboard_id. Jika ingin menentukan dashboard_id kustom, Anda dapat menetapkan kolom name dari objek Dashboard. Format kolom nama terlihat seperti berikut:

"name": "projects/PROJECT_ID/dashboards/DASHBOARD"

gcloud

Untuk membuat dasbor dalam project, gunakan perintah gcloud monitoring dashboards create.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json --project=PROJECT_ID

Sebelum menjalankan perintah sebelumnya, ganti hal berikut:

  • PROJECT_ID: ID project.

Misalnya, jika Anda ingin menduplikasi dasbor, lakukan tindakan berikut:

  1. Selesaikan langkah-langkah di Mendapatkan dasbor untuk mendownload definisi dasbor asli.
  2. Edit JSON yang ditampilkan untuk menghapus kolom etag dan name, serta mengubah nilai kolom displayName.
  3. Jalankan perintah untuk membuat dasbor.

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards create.

Terraform

Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi penyedia Terraform.

Untuk membuat dasbor menggunakan Terraform, lakukan tindakan berikut:

  1. Konfigurasikan project untuk dikelola oleh Terraform.

  2. Gunakan resource Terraform google_monitoring_dashboard.

    Dalam perintah, tetapkan kolom berikut:

    • dashboard_json: Representasi JSON dasbor, menggunakan format Dashboards.

      Untuk contoh format ini, Anda dapat mencantumkan dasbor menggunakan APIs Explorer, atau membuka dasbor di konsol Google Cloud, dan melihat representasi JSON.

    • parent: Nama lengkap project Anda. Misalnya, Anda dapat menetapkan kolom ini ke "projects/PROJECT_ID", dengan PROJECT_ID adalah ID project Google Cloud Anda.

REST

Untuk membuat dasbor baru, kirim permintaan POST ke endpoint Dashboard.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

Sebelum menjalankan perintah sebelumnya, konfigurasikan hal berikut:

  • ${PROJECT_ID}: Variabel lingkungan yang menyimpan project ID tempat membuat dasbor.

Contoh ini membuat dasbor contoh menggunakan file my-dashboard.json. Anda dapat mengelola dasbor melalui konsol Google Cloud.

Untuk konfigurasi dasbor tambahan, lihat Contoh dasbor dan tata letak.

Menghapus dasbor

Untuk menghapus dasbor kustom, panggil metode dashboards.delete dan tentukan dasbor yang ingin Anda hapus.

gcloud

Untuk menghapus dasbor kustom, gunakan gcloud monitoring dashboards delete, dan tentukan ID yang sepenuhnya memenuhi syarat dari dasbor yang akan dihapus:

gcloud monitoring dashboards delete DASHBOARD --project=PROJECT_ID

Sebelum menjalankan perintah sebelumnya, ganti hal berikut:

  • PROJECT_ID: ID project.
  • DASHBOARD: ID dasbor.

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards delete.

Terraform

Anda dapat menghapus resource menggunakan Terraform. Untuk informasi tentang cara menghapus resource, lihat perintah Terraform destroy.

REST

Untuk menghapus dasbor kustom, kirim permintaan DELETE ke endpoint Dashboard, yang memenuhi syarat dengan ID dasbor yang akan dihapus.

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Sebelum menjalankan perintah sebelumnya, konfigurasikan hal berikut:

  • ${PROJECT_ID}: Variabel lingkungan yang menyimpan project ID tempat membuat dasbor.
  • ${DASHBOARD_ID}: Variabel lingkungan yang menyimpan ID dasbor.

Jika berhasil, metode akan menampilkan respons kosong. Jika tidak, error akan ditampilkan.

Cantumkan dasbor

Untuk mencantumkan semua dasbor kustom yang termasuk dalam project, panggil metode dashboards.list dan tentukan project ID.

gcloud

Untuk mencantumkan semua dasbor kustom project, gunakan perintah gcloud monitoring dashboards list:

gcloud monitoring dashboards list --project=PROJECT_ID

Sebelum menjalankan perintah sebelumnya, ganti hal berikut:

  • PROJECT_ID: ID project.

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards list

Terraform

Anda tidak dapat menggunakan Terraform untuk mengirim kueri ke project dengan respons berupa daftar dasbor. Namun, Anda dapat melihat dasbor ini menggunakan konsol Google Cloud.

REST

Untuk mencantumkan semua dasbor kustom project, kirim project ID ke endpoint Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

Sebelum menjalankan perintah sebelumnya, konfigurasikan hal berikut:

  • ${PROJECT_ID}: Variabel lingkungan yang menyimpan project ID tempat membuat dasbor.

Contoh ini menampilkan dasbor kustom yang terkait dengan project Anda.

Memberi nomor halaman pada respons daftar

Metode dashboards.list mendukung penomoran halaman, yang memungkinkan Anda mengambil hasil satu halaman pada satu waktu, bukan semuanya sekaligus.

gcloud

Untuk menentukan jumlah resource per halaman, teruskan flag --page-size dengan perintah. Contoh:

gcloud monitoring dashboards list --page-size=1 --project=PROJECT_ID

Sebelum menjalankan perintah sebelumnya, ganti hal berikut:

  • PROJECT_ID: ID project.

Terraform

Anda tidak dapat menggunakan Terraform untuk mengirim kueri project dengan respons berupa daftar dasbor yang diberi nomor halaman. Namun, Anda dapat melihat dasbor ini menggunakan konsol Google Cloud.

REST

Untuk halaman awal daftar hasil, tentukan parameter kueri pageSize dengan permintaan:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

Sebelum menjalankan perintah sebelumnya, konfigurasikan hal berikut:

  • ${PROJECT_ID}: Variabel lingkungan yang menyimpan project ID tempat membuat dasbor.

Metode ini menampilkan halaman pertama daftar dan nextPageToken. Misalnya:

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Untuk setiap halaman yang tersisa, Anda harus menyertakan nextPageToken yang sesuai dalam permintaan.

Mendapatkan dasbor

Untuk mendapatkan dasbor kustom tertentu untuk project, panggil metode dashboards.get, yang memenuhi syarat dengan ID dasbor.

gcloud

Untuk mendapatkan dasbor kustom tertentu, gunakan perintah gcloud monitoring dashboards describe dan tentukan ID dasbor:

gcloud monitoring dashboards describe DASHBOARD --format=json -project=PROJECT_ID

Sebelum menjalankan perintah sebelumnya, ganti hal berikut:

  • PROJECT_ID: ID project.
  • DASHBOARD: ID dasbor.

Perintah ini menampilkan dasbor yang diminta:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards describe.

Terraform

Anda tidak dapat menggunakan Terraform untuk mengirim kueri project dengan respons berupa dasbor individual. Namun, Anda dapat melihat dasbor ini menggunakan konsol Google Cloud.

REST

Untuk mendapatkan dasbor kustom tertentu, kirim ID dasbor ke endpoint Dashboard.

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Sebelum menjalankan perintah sebelumnya, konfigurasikan hal berikut:

  • ${PROJECT_ID}: Variabel lingkungan yang menyimpan project ID tempat membuat dasbor.
  • ${DASHBOARD_ID}: Variabel lingkungan yang menyimpan ID dasbor.

Dalam ekspresi sebelumnya, ${DASHBOARD_ID} adalah variabel lingkungan yang menyimpan nama dasbor yang sepenuhnya memenuhi syarat.

Metode ini menampilkan respons yang mirip dengan contoh berikut:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

Perbarui dasbor

Untuk memperbarui dasbor kustom yang ada, panggil metode dashboards.patch. Untuk mendapatkan nilai etag saat ini, Anda dapat memanggil metode dashboards.get dan menemukannya dalam respons.

gcloud

Untuk memperbarui dasbor kustom, gunakan gcloud monitoring dashboards update, tentukan ID dasbor yang akan diperbarui, dan berikan perubahan pada dasbor.

gcloud monitoring dashboards update DASHBOARD --config-from-file=my-updated-dashboard.json --project=PROJECT_ID

Sebelum menjalankan perintah sebelumnya, ganti hal berikut:

  • PROJECT_ID: ID project.
  • DASHBOARD: ID dasbor.

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards update.

Contoh sebelumnya memperbarui dasbor kustom yang ada menggunakan file my-updated-dashboard.json. Respons, yang menyertakan nilai etag baru, adalah salinan listingan dasbor yang diperbarui.

Terraform

Untuk mempelajari cara menerapkan atau menghapus konfigurasi Terraform, lihat Perintah dasar Terraform. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi penyedia Terraform.

Untuk memperbarui dasbor menggunakan Terraform, lakukan langkah berikut:

  1. Konfigurasikan project untuk dikelola oleh Terraform.

  2. Gunakan resource Terraform google_monitoring_dashboard.

    Dalam perintah, tetapkan kolom berikut:

    • dashboard_json: Representasi JSON dasbor, menggunakan format Dashboards.

    • parent: Nama lengkap project Anda. Misalnya, Anda dapat menetapkan kolom ini ke "projects/PROJECT_ID", dengan PROJECT_ID adalah ID project Google Cloud Anda.

REST

Untuk memperbarui dasbor kustom, kirim permintaan PATCH ke endpoint Dashboard dan berikan objek Dashboard yang telah direvisi dan nilai etag dari respons dashboards.get terbaru.

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Sebelum menjalankan perintah sebelumnya, konfigurasikan hal berikut:

  • ${PROJECT_ID}: Variabel lingkungan yang menyimpan project ID tempat membuat dasbor.
  • ${DASHBOARD_ID}: Variabel lingkungan yang menyimpan ID dasbor.

Contoh sebelumnya memperbarui dasbor kustom yang ada menggunakan file my-updated-dashboard.json. Respons, yang menyertakan nilai etag baru, adalah salinan listingan dasbor yang diperbarui.

Langkah berikutnya