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.
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 MenggunakantimeSeries.query.Untuk memilih dan memanipulasi data deret waktu untuk diagram, Anda memberikan kueri ke spesifikasi
TimeSeriesQuerysaat memanggil metodedashboards.create. Untuk contoh, lihat Membuat diagram.Untuk membuat kondisi berbasis MQL dalam kebijakan pemberitahuan, jelaskan kondisi untuk kebijakan pemberitahuan dengan jenis kondisi
MonitoringQueryLanguageConditionsaat Anda memanggilalertPolicies.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:
timeSeriesDescriptormenjelaskan kunci label, nilai label, dan titik data dalam tabel. Isinya tidak berisi data; hanya mendeskripsikan data.timeSeriesDataberisi 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.
- Item pertama dalam pasangan,
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.
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:
Buat variabel lingkungan untuk menyimpan ID project cakupan Anda dari cakupan metrik. Langkah-langkah ini memanggil variabel
PROJECT_ID:PROJECT_ID=a-sample-projectLakukan autentikasi ke Google Cloud CLI:
gcloud auth loginOpsional. 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}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.
Untuk memverifikasi bahwa Anda mendapatkan token akses, lakukan echo variabel
TOKEN:echo ${TOKEN} ya29.GluiBj8o....