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 contoh tersebut menunjukkan cara menggunakan Google Cloud CLI. Meskipun Anda juga dapat mengelola dasbor kustom melalui Google Cloud Console, API memberi Anda cara terprogram untuk mengelola banyak dasbor secara bersamaan.

Endpoint mendukung metode berikut untuk mengelola dan mengonfigurasi dasbor:

• dashboards.create: membuat dasbor
• dashboards.delete: menghapus dasbor tertentu
• dashboards.list: mengambil daftar semua dasbor dalam project tertentu
• dashboards.get: mengambil dasbor yang ditentukan
• dashboards.patch: memperbarui struktur dasbor yang ditentukan

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

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

Sebelum memulai

Saat membuat dasbor, Anda harus menentukan komponen, atau widget, yang ingin ditampilkan, dan tata letak untuk widget tersebut. Anda juga dapat menambahkan filter permanen ke dasbor.

Tata letak dasbor

Tata letak menentukan bagaimana 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 beberapa baris dan mengatur kumpulan widget secara horizontal di setiap baris.

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

Misalnya, gambar berikut 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 diagram dan tabel:

  • XyChart: menampilkan data menggunakan sumbu X dan Y. Diagram berikut adalah instance dari widget XyChart:

  • Diagram garis

  • Diagram batang

  • Diagram area bertumpuk (stacked area chart)

  • Peta panas

  • Membuat log diagram Analytics

  • Widget SLO, tetapi tidak didukung untuk membuat diagram SLO menggunakan API.

  Jika membuat diagram garis, diagram batang bertumpuk, atau diagram area bertumpuk, Anda dapat menentukan bahwa metrik merujuk pada sumbu Y kiri atau kanan. Jika beberapa metrik dibuat dalam diagram, Anda dapat menggunakan kedua sumbu Y.

  • PieChart: menampilkan nilai terbaru metrik, dengan setiap deret waktu berkontribusi pada satu irisan ke lingkaran.

  • Scorecard: menampilkan nilai terbaru metrik, dan bagaimana nilai ini berkaitan dengan satu atau beberapa nilai minimum.

  • TimeSeriesTable: menampilkan nilai terbaru metrik. Anda dapat mengurutkan tabel berdasarkan kolom, memfilter tabel, dan menambahkan atau menghapus kolom dari layar.

• Diagram pemberitahuan dan widget insiden:

  • AlertChart: menampilkan ringkasan kebijakan pemberitahuan kondisi tunggal. Widget ini menampilkan data sebagai diagram garis, menunjukkan batas, dan mencantumkan jumlah insiden terbuka.

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

• Widget log dan error:

  • ErrorReportingPanel: menampilkan grup error yang disimpan di project Google Cloud yang dipilih.

  • LogsPanel: menampilkan entri log cakupan project yang disimpan di project Google Cloud saat ini. Anda dapat mengonfigurasi widget untuk menampilkan entri log yang disimpan di project Google Cloud yang dapat diakses melalui cakupan metrik saat ini.

• Widget teks dan pengaturan:

  Untuk menyertakan widget ini di dasbor, dasbor harus memiliki MosaicLayout.

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

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

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

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

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

Misalnya, gambar berikut menunjukkan representasi JSON dari 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"
          }
        }
      }
    ]
  }
}

Filter dasbor

Saat mendesain dasbor, Anda mungkin mengidentifikasi beberapa cara untuk melihat data yang ditampilkan di dasbor. Misalnya, saat dasbor menampilkan metrik untuk instance virtual machine (VM), Anda mungkin ingin melihat metrik untuk semua VM dan ingin melihat metrik untuk zona tertentu. Dalam situasi ini, sebaiknya buat filter permanen dan tetapkan nilai default filter tersebut ke tampilan yang paling umum digunakan. Filter permanen dapat berlaku untuk beberapa atau semua widget dasbor. Saat menampilkan dasbor dengan Konsol Google Cloud, toolbar dasbor akan menampilkan filter permanen dan menu yang dapat digunakan untuk mengubah nilai filter untuk sementara.

Ada beberapa jenis filter dasbor permanen:

• Filter di seluruh dasbor berlaku untuk semua widget di dasbor yang mendukung label filter dan yang tidak menentukan nilai untuk label tersebut.

  Misalnya, saat diagram menyertakan filter zone = us-central1-a, diagram tersebut akan mengabaikan filter dasbor yang didasarkan pada label zone. Demikian pula, diagram tanpa label zone akan mengabaikan filter dasbor dengan label ini.

• Variabel template adalah variabel bernama yang berlaku untuk widget tertentu. Setiap variabel ditujukan untuk label dan nilai tertentu. Anda menentukan widget mana yang menerapkan variabel template.

Semua jenis filter diwakili dengan struktur data yang sama. Untuk informasi selengkapnya, lihat DashboardFilter.

Misalnya, gambar berikut menunjukkan representasi JSON parsial dari dasbor yang menentukan variabel template dan filter seluruh dasbor:

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

Dalam JSON yang ditampilkan, entri pertama dalam struktur dashboardFilters adalah untuk variabel template dengan nama iid dan filter seluruh dasbor dengan kunci label zone. Variabel template adalah alias dari label instance_id.

Struktur data untuk variabel template tidak mencantumkan widget tempat variabel tersebut diterapkan. Sebagai gantinya, Anda dapat mengaitkan widget dengan variabel template dengan memodifikasi kueri widget untuk menyertakan referensi ke variabel tersebut. Saat widget ditampilkan di dasbor, nilai variabel template akan di-resolve.

Lihat bagian berikut untuk mengetahui cara menganotasi panel log dan diagram:

• Panel log
• Diagram dan tabel yang ditentukan MQL
• Diagram dan tabel yang ditentukan PromQL
• Diagram dan tabel yang ditentukan dengan filter deret waktu

Panel log

Untuk mengonfigurasi panel log guna memfilter tampilan berdasarkan nilai variabel template, tambahkan variabel ke panel kueri. Contoh berikut menunjukkan kueri yang memfilter menurut nilai variabel template iid:

${iid}

Sebelum panel log membuat kueri untuk log yang akan ditampilkan, variabel template telah di-resolve. Dalam contoh ini, jika nilai variabel template adalah "12345", ${iid} akan diganti dengan pernyataan resource.labels."instance_id"="12345".

Anda juga dapat menyertakan hanya nilai variabel template dalam kueri. Sebaiknya hanya gunakan nilai sebagai bagian dari filter yang ditentukan dengan ekspresi reguler. Misalnya, kueri berikut menggunakan ekspresi reguler untuk mencocokkan entri log yang memiliki payload JSON yang berisi string yang dijelaskan:

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

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

Tabel berikut menunjukkan cara variabel template diselesaikan oleh panel log:

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

Diagram dan tabel yang ditentukan MQL

Saat Anda menggunakan Bahasa Kueri Monitoring (MQL) untuk mengonfigurasi diagram, tambahkan pipa dan variabel ke string kueri:

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

Sebelum kueri diagram untuk deret waktu ditampilkan, variabel template telah di-resolve. Dalam contoh ini, jika nilai variabel template adalah "12345", ${iid} akan diganti dengan pernyataan filter (resource.instance_id == '12345'). Filter ini cocok dengan deret waktu yang memiliki label bernama resource.instance_id, dan hanya jika nilai label tersebut persis 12345.

Jika Anda ingin memfilter deret waktu menggunakan ekspresi reguler, konfigurasikan kueri untuk hanya menyertakan nilai variabel template. Untuk mengilustrasikan sintaksis, contoh berikut menunjukkan cara menggunakan ekspresi reguler untuk menentukan apakah nilai label resource.instance_id berisi nilai variabel template iid:

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

Tabel berikut menunjukkan cara variabel template diselesaikan untuk kueri MQL:

Sintaksis	Nilai Dipilih	Ekspresi MQL yang diselesaikan
${iid}	12345	filter (resource.instance_id == '12345')
${iid}	*	filter (true)
${iid.value}	12345	12345
${iid.value}	*	.*

Diagram dan tabel yang ditentukan PromQL

Saat Anda menentukan diagram menggunakan PromQL, tambahkan variabel yang digabungkan dengan tanda kurung kurawal pada string kueri:

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

Sebelum kueri diagram untuk deret waktu ditampilkan, variabel template telah di-resolve. Dalam contoh ini, jika nilai variabel template adalah "12345", ${iid} akan diganti dengan pernyataan instance_id == '12345'.

Mirip dengan MQL, saat Anda menentukan widget dengan PromQL, kueri hanya dapat mengekstrak nilai variabel template. Sebaiknya hanya gunakan nilai sebagai bagian dari filter yang ditentukan dengan ekspresi reguler. Untuk menggambarkan sintaksis, contoh berikut menunjukkan cara menggunakan ekspresi reguler untuk menentukan apakah nilai label instance_id berisi nilai variabel template iid:

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

Tabel berikut menunjukkan cara variabel template diselesaikan untuk kueri PromQL:

Sintaksis	Nilai Dipilih	Ekspresi PromQL yang diselesaikan
${iid}	12345	instance_id == '12345'
${iid}	*	noop_filter=~".*"
${iid.value}	12345	12345
${iid.value}	*	.+

Diagram dan tabel yang ditentukan dengan filter deret waktu

Saat Anda menentukan diagram menggunakan filter deret waktu, tambahkan variabel ke string filter:

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

Tidak seperti diagram yang ditentukan MQL dan PromQL, Anda tidak dapat menggunakan nilai variabel template dalam filter deret waktu.

Tabel berikut menunjukkan cara variabel template diselesaikan:

Sintaksis	Nilai Dipilih	Ekspresi filter terselesaikan
${iid}	12345	resource.instance_id == "12345"
${iid}	*	Dihilangkan
${iid.value}	12345	Tidak didukung
${iid.value}	*	Tidak didukung

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 menghasilkan dashboard_id. Jika ingin menentukan dashboard_id kustom, Anda dapat menetapkan kolom name dari objek Dashboard. Format kolom nama akan terlihat seperti berikut:

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

Protocol

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

gcloud

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

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

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

1. Selesaikan langkah-langkah di Dapatkan 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.

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

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 dihapus.

Protocol

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

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

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

gcloud

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

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards delete.

Cantumkan dasbor

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

Protocol

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

gcloud

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

gcloud monitoring dashboards list

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards list.

Contoh tersebut menampilkan dasbor kustom yang terkait dengan project Anda.

Memberi nomor pada respons daftar

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

Protocol

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

Metode ini akan menampilkan halaman pertama dari 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.

gcloud

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

gcloud monitoring dashboards list --page-size=1

Dapatkan dasbor

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

Protocol

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}

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

gcloud

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

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

Perintah tersebut akan 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.

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.

Protocol

Untuk memperbarui dasbor kustom, kirim permintaan PATCH ke endpoint Dashboard, lalu berikan objek Dashboard yang 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}

gcloud

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

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

Untuk informasi selengkapnya, lihat referensi gcloud monitoring dashboards update.

Contoh ini memperbarui dasbor kustom yang ada menggunakan file my-updated-dashboard.json dan menampilkan salinan listingan dasbor yang diperbarui. Data yang ditampilkan menyertakan nilai etag baru.

Langkah selanjutnya

• Contoh dasbor dan tata letak
• Membuat dan mengelola dasbor kustom dengan Konsol Google Cloud