Menggunakan MQL dari Monitoring API

Halaman ini menjelaskan cara menyediakan kueri Bahasa Kueri Monitoring (MQL) ke Cloud Monitoring API.

Halaman ini tidak membahas pembuatan kueri MQL. Untuk kumpulan contoh kueri, lihat Contoh. Rujukan MQL memberikan referensi yang komprehensif untuk bahasa tersebut.

Untuk mengetahui informasi umum tentang kebijakan pemberitahuan berbasis MQL, baca Kebijakan pemberitahuan dengan MQL.

Catatan: Editor kode memungkinkan rentang waktu ditentukan secara eksplisit dalam kueri, dan secara implisit oleh opsi diagram di editor. Jika Anda menyalin kueri MQL dari editor, dan menggunakan pemilihan waktu berbasis diagram yang implisit, kueri tersebut mungkin tidak valid jika Anda mencoba menyediakannya langsung ke API. Untuk mengetahui informasi selengkapnya, lihat Rentang waktu, diagram, dan editor kode.

Menggunakan MQL dari API

Anda dapat memberikan kueri MQL di tempat berikut di Monitoring API:

• Untuk memilih dan memanipulasi data deret waktu menggunakan MQL, panggil metode timeSeries.query. Untuk mengetahui contohnya, lihat Menggunakan timeSeries.query.

• Untuk memilih dan memanipulasi data deret waktu untuk diagram, Anda memberikan kueri ke spesifikasi TimeSeriesQuery saat memanggil metode dashboards.create. Untuk contoh, lihat Membuat diagram.

• Untuk membuat kondisi berbasis MQL dalam kebijakan pemberitahuan, jelaskan kondisi untuk kebijakan pemberitahuan dengan jenis kondisi MonitoringQueryLanguageCondition saat Anda memanggil alertPolicies.create. Misalnya, lihat Membuat kondisi untuk kebijakan pemberitahuan.

Mengambil data dengan timeSeries.query

Untuk mengambil data deret waktu dari API dengan kueri MQL, gunakan metode timeSeries.query.

Metode timeSeries.query menggunakan struktur minimal yang terlihat seperti ini di JSON:

{
  "query": string
}

Untuk nilai kolom query, tentukan string di MQL, seperti yang ditunjukkan dalam kueri sederhana berikut:

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | within 5m"
}

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | for 1h"
}

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/usage_time | sum | next_older 10m | every 10m"
}

Jika kueri membuat tabel output yang tidak selaras, Anda harus menyediakan durasi dengan menggunakan operasi tabel within saat memanggil API secara langsung. Alat diagram seperti Metrics Explorer menyediakan durasi kueri default. Kueri dalam cuplikan JSON berikut berfungsi di editor kode MQL di Metrics Explorer, tetapi gagal saat diberikan langsung ke API:

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10)"
}

Dengan penambahan operasi tabel within ke kueri sebelumnya, contoh sebelumnya dapat diberikan langsung ke API:

{
   "query": "fetch gce_instance::compute.googleapis.com/instance/disk/read_bytes_count | mul(10) | within 1h"
}

Untuk bereksperimen dengan API, Anda dapat menggunakan alat APIs Explorer di halaman referensi timeSeries.query. Untuk pengantar alat APIs Explorer, lihat APIs Explorer.

Cara lain untuk mencoba API adalah dengan memasukkan kueri ke dalam file teks, lalu mengeksekusi kueri tersebut menggunakan curl. Contoh berikut meneruskan kueri dalam file query.json ke metode timeSeries.query:

curl -d @query.json -H "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" -X POST \
https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/timeSeries:query

Untuk informasi selengkapnya tentang penggunaan curl, lihat Memanggil curl.

Jika berhasil, kueri akan menampilkan tabel yang berisi deret waktu yang diminta. Tabel ini dibagi menjadi dua komponen:

• timeSeriesDescriptor menjelaskan kunci label, nilai label, dan titik data dalam tabel. Isinya tidak berisi data; hanya mendeskripsikan data.

• timeSeriesData berisi data yang dijelaskan dalam deskripsi deret waktu. Data ini disajikan sebagai array pasangan.

  • Item pertama dalam pasangan, labelValues, mencatat kumpulan nilai untuk label yang tercantum dalam deskripsi deret waktu.
  • Yang kedua, pointData, adalah array tersemat yang berisi pasangan nilai/stempel waktu, yang mewakili data yang dikumpulkan dengan kumpulan nilai label yang ditentukan.

Respons, yang sedikit diformat ulang, terlihat seperti ini:

[{
  "timeSeriesTable": {
    "timeSeriesDescriptor": {
      "labelDescriptors": [
        { "key": "resource.project_id" },
        { "key": "resource.zone" },
        { "key": "resource.instance_id" },
        { "key": "metric.instance_name" }
      ],
      "valueDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ],
      "pointDescriptors": [
        {
          "key": "value.utilization",
          "valueType": "DOUBLE",
          "metricKind": "GAUGE"
        }
      ]
    },
    "timeSeriesData": [
      {
        "labelValues": [
          { "stringValue": "632526624816" },
          { "stringValue": "us-central1-a" },
          { "stringValue": "5106847938297466291" },
          { "stringValue": "gke-kuber-cluster-default-pool-6fe301a0-n8r9" }
        ],
        "pointData": [
          {
            "values": [
              {
                "doubleValue": 0.063896992710942874
              }
            ],
            "timeInterval": {
              "startTime": "1969-12-31T23:59:59.999999Z",
              "endTime": "2020-03-02T20:17:00Z"
            }
          },
          { ... additional value/timestamp pairs ...}
        ]
      },
      { ... additional labelValue/pointData pairs ...},
    ]
  }

Membuat bagan

Anda dapat menggunakan metode dashboards.create untuk membuat dasbor dan diagram secara terprogram.

Satu-satunya perbedaan antara pembuatan diagram berbasis MQL dan diagram lainnya adalah jenis kueri TimeSeriesQuery yang Anda gunakan untuk mengisi set data diagram.

Membuat diagram berbasis MQL

Untuk kueri MQL, gunakan kueri tersebut sebagai nilai kolom string timeSeriesQueryLanguage dalam array DataSet diagram.

Berikut adalah definisi dasbor sederhana yang mencakup MQL:

{
  "displayName": "Dashboard for MQL chart (API)",
  "gridLayout": {
    "widgets": [
      {
        "title": "Min/Max Compute Engine CPU utilization",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesQueryLanguage": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | within(1h) | { top 1, max(val()) ; bottom 1, min(val()) } | union"
              },
              "plotType": "LINE",
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

Tindakan ini akan membuat dasbor berjudul "Dashboard for MQL chart (API)" di project Anda. Dasbor ini berisi diagram yang disebut "Penggunaan CPU Compute Engine Min/Max", yang menampilkan dua baris, satu untuk nilai tertinggi dan satu untuk yang terendah.

Untuk mengetahui informasi selengkapnya tentang contoh kueri ini, lihat Menggabungkan pilihan dengan union.

Membuat diagram

Anda dapat memasukkan JSON dasbor ke dalam file, lalu meneruskan file tersebut ke gcloud beta monitoring dashboards create atau menggunakan curl untuk mempostingnya ke https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards. Untuk contoh lainnya, lihat Membuat dasbor. Untuk informasi selengkapnya tentang penggunaan curl, lihat Memanggil curl.

Untuk informasi umum tentang membuat diagram dan dasbor, lihat Mengelola dasbor menurut API. Untuk materi referensi, lihat Dashboards.

Membuat kondisi untuk kebijakan pemberitahuan

Anda menggunakan metode alertPolicies.create untuk membuat kebijakan pemberitahuan secara terprogram.

Satu-satunya perbedaan antara membuat kebijakan pemberitahuan berbasis MQL dan kebijakan pemberitahuan lainnya adalah jenis Condition yang Anda gunakan. Jika tidak, Anda akan membuat kebijakan ini seperti kebijakan pemberitahuan lainnya.

Tabel berikut menunjukkan kueri MQL sederhana untuk kondisi kebijakan pemberitahuan yang menguji pemakaian CPU Compute Engine melebihi 15 persen:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| group_by sliding(5m), mean(val())
| condition val() > 0.15 '10^2.%'

Untuk mengetahui informasi selengkapnya tentang operasi pemberitahuan condition MQL, lihat Kebijakan pemberitahuan dengan MQL.

Membuat kebijakan pemberitahuan

Untuk membuat kebijakan pemberitahuan berdasarkan kueri MQL, gunakan jenis kondisi AlertPolicy MonitoringQueryLanguageCondition. MonitoringQueryLanguageCondition memiliki struktur berikut:

{
  "query":    string,
  "duration": string,
  "trigger":  {
    object (Trigger)
  }
}

Nilai kolom query adalah string kueri pemberitahuan MQL dalam bentuk yang ringkas atau ketat. Contoh dalam dokumen ini dalam bentuk yang ringkas. Untuk informasi selengkapnya tentang formulir ketat, lihat Kueri bentuk ketat.

Kolom duration menentukan durasi waktu saat setiap evaluasi kueri harus menghasilkan nilai true sebelum kebijakan pemberitahuan dipicu. Untuk mengetahui informasi selengkapnya, lihat Perilaku kebijakan pemberitahuan berbasis metrik. Nilai harus berupa jumlah menit, yang dinyatakan dalam detik; misalnya, 600s untuk durasi 10 menit.

Kolom trigger menentukan berapa banyak deret waktu yang harus memenuhi kondisi selama periode duration, yang dinyatakan sebagai jumlah atau persentase. Nilai defaultnya adalah jumlah 1. Untuk informasi selengkapnya, lihat Trigger.

Untuk contoh kueri pemberitahuan, dengan durasi 10 menit dan jumlah pemicu 1, strukturnya terlihat seperti berikut:

{
  "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
  "duration": "600s",
  "trigger" : {
     "count": 1
  }
}

Gunakan struktur ini sebagai nilai kolom conditionMonitoringQueryLanguage dalam suatu kondisi, yang kemudian disematkan dalam struktur kebijakan pemberitahuan. Untuk mengetahui informasi selengkapnya tentang struktur ini, lihat AlertPolicy.

Catatan: Kebijakan pemberitahuan yang menggunakan MQL hanya dapat memiliki satu kondisi berbasis MQL. Kebijakan dengan beberapa kondisi tidak akan didukung jika suatu kondisi menggunakan MQL.

Berikut adalah kebijakan minimal yang lengkap dengan kondisi MonitoringQueryLanguageCondition di JSON:

{
  "displayName":"Alert if CPU utilization exceeds 15% for 10 mins (MQL, API)",
  "combiner":"OR",
  "conditions":[
    {
      "displayName":"MQL-based utilization condition, API",

      "conditionMonitoringQueryLanguage":
      {
        "query": "fetch gce_instance::compute.googleapis.com/instance/cpu/utilization | group_by sliding(5m), mean(val()) | condition val() > 0.15 '10^2.%'",
        "duration": "600s",
        "trigger" : {
           "count": 1
        },
     },
   }
  ],
}

Membuat kebijakan pemberitahuan

Untuk membuat kebijakan, Anda dapat memasukkan JSON kebijakan pemberitahuan ke dalam file, lalu meneruskan file tersebut ke gcloud alpha monitoring policies create atau menggunakan curl untuk mempostingnya ke https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/alertPolicies.

Untuk mengetahui informasi selengkapnya tentang Monitoring API untuk kebijakan pemberitahuan, lihat Mengelola kebijakan pemberitahuan dengan API.

Untuk informasi selengkapnya tentang penggunaan curl, lihat Memanggil curl.

Memanggil curl

Setiap pemanggilan curl menyertakan sekumpulan argumen, diikuti dengan URL resource API. Argumen umum mencakup project ID Google Cloud dan token autentikasi. Nilai ini diwakili di sini oleh variabel lingkungan PROJECT_ID dan TOKEN.

Anda mungkin juga harus menentukan argumen lain, misalnya, untuk menentukan jenis permintaan HTTP (misalnya -X DELETE). Permintaan defaultnya adalah GET, jadi contoh tidak menentukannya.

Setiap panggilan curl memiliki struktur umum berikut:

curl --http1.1 --header "Authorization: Bearer ${TOKEN}" <other_args> https://monitoring.googleapis.com/v3/projects/${PROJECT_ID}/<request>

Untuk menggunakan curl, Anda harus menentukan project ID dan token akses. Untuk mengurangi pengetikan dan error, Anda dapat memasukkannya ke dalam variabel lingkungan dengan cara meneruskannya ke curl.

Untuk menetapkan variabel ini, lakukan langkah berikut:

1. Buat variabel lingkungan untuk menyimpan ID project cakupan Anda dari cakupan metrik. Langkah-langkah ini memanggil variabel PROJECT_ID:

   PROJECT_ID=a-sample-project
   

2. Lakukan autentikasi ke Google Cloud CLI:

   gcloud auth login
   

3. Opsional. Agar tidak perlu menentukan project ID dengan setiap perintah gcloud, tetapkan project ID sebagai default dengan menggunakan gcloud CLI:

   gcloud config set project ${PROJECT_ID}
   

4. Buat token otorisasi dan simpan dalam variabel lingkungan. Langkah-langkah ini memanggil variabel TOKEN:

   TOKEN=`gcloud auth print-access-token`
   

   Anda harus memperbarui token akses secara berkala. Jika perintah yang berfungsi tiba-tiba melaporkan bahwa Anda tidak diautentikasi, buat ulang perintah ini.

5. Untuk memverifikasi bahwa Anda mendapatkan token akses, lakukan echo variabel TOKEN:

   echo ${TOKEN}
   ya29.GluiBj8o....