Tentang bahasa MQL

Halaman ini memberikan informasi umum tentang Bahasa Kueri Monitoring (MQL), termasuk topik berikut:

• Pintasan kueri untuk operasi dan fungsi tabel.
• Variasi pada operasi fetch MQL.
• Kueri dengan format ketat.
• Aturan untuk mencocokkan kolom resource.project_id.
• Cara "efek tepi" dapat memengaruhi rasio yang dihitung di seluruh jenis metrik.
• Format tanggal yang didukung oleh MQL.
• Batasan pada panjang dan kompleksitas kueri.
• Makro di MQL.

Informasi ini berlaku, baik Anda menggunakan MQL dari Konsol Google Cloud maupun dari Cloud Monitoring API. Untuk mengetahui informasi tentang struktur kueri MQL, baca Contoh.

Pintasan untuk operasi dan fungsi tabel

Kueri biasanya terdiri dari rantai operasi tabel terhubung yang dihubungkan dengan pipa (|), yang masing-masing dimulai dengan nama operasi tabel, diikuti dengan daftar ekspresi. Ekspresi dapat berisi panggilan fungsi yang mencantumkan semua argumennya secara eksplisit. Namun, Bahasa Kueri Monitoring memungkinkan kueri diekspresikan dengan sejumlah pintasan.

Bagian ini menjelaskan pintasan untuk operasi tabel, menggunakan fungsi sebagai operasi tabel, dan pintasan untuk kolom nilai sebagai argumen ke fungsi.

Untuk daftar lengkapnya, lihat Pintasan operasi tabel.

Pintasan untuk operasi tabel

Jika menggunakan operasi fetch, group_by, dan filter, Anda dapat menghilangkan operasi tabel eksplisit jika argumen cukup untuk menentukan operasi yang diinginkan. Misalnya, kueri berikut:

gce_instance::compute.googleapis.com/instance/cpu/utilization

setara dengan:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization

Operasi group_by berikut adalah setara:

         [zone], mean(val())
group_by [zone], mean(val())

Anda dapat menghapus kata filter jika memberi tanda kurung pada pengujian filter. Misalnya, dua operasi filter berikut adalah setara:

       (instance_name =~ 'apache.*')
filter instance_name =~ 'apache.*'

Anda dapat menggabungkan formulir pintasan ini dalam kueri. Misalnya, kueri berikut:

gce_instance::compute.googleapis.com/instance/cpu/utilization
| (instance_name =~ 'apache.*')
|  [zone], mean(val())

sama dengan bentuk yang lebih eksplisit ini:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| filter instance_name =~ 'apache.*'
| group_by [zone], mean(val())

Untuk mengetahui informasi selengkapnya tentang pintasan operasi tabel, lihat Pintasan operasi tabel dalam referensi MQL.

Menggunakan fungsi sebagai operasi tabel

Operasi tabel biasanya dimulai dengan nama operasi tabel. Namun, MQL memungkinkan operasi tabel dimulai dengan nama fungsi.

Anda dapat menggunakan nama fungsi jika fungsi bernama melakukan beberapa transformasi kolom nilai tabel input. Penggantian ini adalah pintasan untuk operasi tabel group_by, align, atau value, bergantung pada jenis fungsi yang namanya diberikan.

Bentuk umumnya adalah:

|  FUNCTION_NAME ARG, ARG ... 

Dalam operasi tabel, fungsi menggunakan kolom nilai tabel input sebagai argumen, argumen diikuti oleh argumen apa pun untuk fungsi itu sendiri. Saat menggunakan fungsi sebagai operasi tabel, Anda menentukan argumen dalam bentuk operasi tabel, sebagai daftar yang dipisahkan koma, bukan dengan tanda kurung di sekeliling (()) yang biasanya digunakan dengan fungsi.

Operasi tabel lengkap yang dihasilkan dengan memperluas pintasan bergantung pada jenis fungsi:

• group_by: Jika Anda menggunakan fungsi agregasi dengan operasi group_by yang menggabungkan semua kolom ID deret waktu (yaitu, menggunakan [] untuk pengelompokan), Anda dapat menggunakan fungsi tersebut sebagai pintasan. Misalnya,

  | distribution powers_of(1.1)

  adalah jalan pintas untuk

  | group_by [], distribution(val(0), powers_of(1.1))

• align: Jika menggunakan fungsi perataan sebagai argumen untuk operasi align, Anda dapat menggunakan fungsi sebagai pintasan. Misalnya,

  | delta

  adalah jalan pintas untuk

  | align delta()

  Demikian pula,

  | rate 10m

  adalah jalan pintas untuk

  | align rate(10m)

  Perhatikan bahwa fungsi aligner menggunakan deret waktu input sebagai argumen implisit, sehingga kolom nilai tidak diberikan secara eksplisit di sini.

• value: Semua fungsi lainnya dapat bertindak sebagai pintasan untuk operasi tabel value. Misalnya,

  | mul 3.3

  adalah jalan pintas untuk

  | value mul(val(0), 3.3)

  Demikian pula,

  | div

  adalah jalan pintas untuk

  | value div(val(0), val(1))

  Perhatikan bahwa div akan pintasan operasi tabel input dengan dua kolom nilai dan menghasilkan operasi tabel dengan satu kolom nilai yang merupakan rasionya.

Pintasan untuk fungsi kolom nilai

Anda dapat menggunakan .function sebagai pintasan untuk function(val()) jika ada satu kolom nilai dalam input, atau sebagai pintasan untuk function(val(0), val(1)) jika ada dua kolom nilai, dan seterusnya.

Titik di awal berarti, “Memanggil fungsi berikut, yang menyediakan kolom nilai poin input (atau beberapa kolom) sebagai argumen untuk fungsi tersebut”.

Misalnya, .mean adalah pintasan untuk mean(val()). Berikut ini setara:

group_by [zone], .mean
group_by [zone], mean(val())

Jika tabel input memiliki beberapa kolom nilai, setiap kolom akan menjadi argumen untuk fungsi di pintasan ini. Misalnya, jika tabel input memiliki dua kolom nilai, maka

.div

adalah jalan pintas untuk

div(val(0), val(1))

Dengan pintasan ini, Anda dapat menyediakan argumen yang tidak merujuk ke kolom nilai. Argumen tambahan diberikan setelah argumen kolom nilai. Misalnya, jika tabel input memiliki satu kolom nilai, maka

.div(3)

setara dengan

div(val(0), 3)

Variasi pada fetch

Operasi fetch biasanya menampilkan tabel deret waktu yang diberi nama oleh sepasang jenis metrik dan resource yang dimonitor. Contoh:

fetch gce_instance :: compute.googleapis.com/instance/cpu/utilization

Jika metrik hanya berlaku untuk satu jenis resource yang dimonitor, Anda dapat menghilangkan resource yang dimonitor dari kueri. Kueri berikut setara dengan kueri sebelumnya, karena metrik penggunaan CPU hanya berlaku untuk resource yang dipantau gce_instance:

fetch compute.googleapis.com/instance/cpu/utilization

Operasi fetch hanya dapat menentukan jenis resource yang dimonitor, dengan metrik yang ditentukan dalam operasi metric berikutnya. Misalnya, contoh ini setara dengan contoh fetch sebelumnya:

fetch gce_instance
| metric metric compute.googleapis.com/instance/cpu/utilization

Memisahkan fetch dengan cara ini akan berguna ketika Anda ingin mengambil dua metrik berbeda untuk resource yang dipantau yang sama. Misalnya, kueri berikut menghitung jumlah paket per CPU-detik yang terpakai:

fetch gce_instance
| {
    metric compute.googleapis.com/instance/network/received_packets_count ;
    metric compute.googleapis.com/instance/cpu/usage_time
  }
| ratio

Memisahkan fetch juga memungkinkan Anda menerapkan pemfilteran hanya ke label resource yang dipantau:

fetch gce_instance
| filter resource.zone =~ "asia.*"
| {
    metric compute.googleapis.com/instance/network/received_packets_count ;
    metric compute.googleapis.com/instance/cpu/usage_time
  }
| ratio

fetch yang hanya menyebutkan jenis resource yang dimonitor harus diikuti dengan operasi metric, mungkin dengan operasi filter yang mengintervensi.

Kueri berformat ketat

Kueri ketat adalah kueri yang tidak menggunakan pintasan atau nilai implisit apa pun dalam kueri yang ringkas. Kueri ketat memiliki karakteristik berikut:

• Semua pintasan akan diganti.
• Semua argumen implisit dijadikan eksplisit.
• Kolom dirujuk dengan nama lengkap.
• Kolom baru secara eksplisit diberi nama.
• Setiap operasi penyelarasan yang disediakan secara implisit diberikan secara eksplisit.

Menggunakan bentuk ketat membuat kueri lebih tahan terhadap perubahan dalam struktur tabel input, dan dapat memperjelas apa yang dilakukan kueri. Memasukkan kueri dalam bentuk yang ketat tidak membuat kueri lebih efisien.

Ketika Anda menyimpan kueri untuk diagram, kueri tersebut dikonversi menjadi bentuk ketat. Dialog konfirmasi untuk operasi simpan akan menampilkan formulir ketat.

Kueri ringkas untuk kebijakan pemberitahuan tidak dikonversi ke bentuk ketat. Kueri untuk kebijakan pemberitahuan disimpan saat Anda menyediakannya; Anda dapat menggunakan bentuk yang ringkas atau ketat.

Dengan tersedianya pintasan dan formulir ketat, Anda mungkin menemukan kueri MQL setara yang terlihat sangat berbeda satu sama lain. Misalnya, kueri berikut, yang menghitung jumlah paket yang diterima per CPU yang terpakai, menggunakan banyak pintasan:

gce_instance
| (zone =~ ".*-a")
| {
    compute.googleapis.com/instance/network/received_packets_count ;
    compute.googleapis.com/instance/cpu/usage_time
  }
| join
| div

Saat Anda menyimpan kueri ini ke diagram atau sebagai bagian dari kebijakan pemberitahuan, kueri formulir ketat yang dihasilkan akan melakukan hal yang sama persis. Namun, bentuk ketat mungkin terlihat sangat berbeda, seperti yang ditunjukkan dalam contoh berikut:

fetch gce_instance
| filter (resource.zone =~ '.*-a')
| { t_0:
      metric 'compute.googleapis.com/instance/network/received_packets_count'
      | align delta() ;
    t_1:
      metric 'compute.googleapis.com/instance/cpu/usage_time'
      | align delta() }
| join
| value [v_0: div(t_0.value.received_packets_count, t_1.value.usage_time)]

Saat Anda mengedit definisi diagram yang tersimpan, editor kode akan menampilkan formulir ketat.

Mencocokkan kolom resource.project_id

Project Google Cloud memiliki nama tampilan, yang muncul di menu tetapi tidak mengidentifikasi project secara unik. Nama tampilan project mungkin adalah "Demo Monitoring".

Project juga memiliki dua kolom yang berfungsi sebagai ID:

• Project ID: ID string unik. Hal ini sering kali didasarkan pada nama tampilan. ID project ditetapkan saat project dibuat, biasanya dengan menggabungkan elemen-elemen nama project dan mungkin menambahkan angka di akhir, jika diperlukan untuk keunikan. Project ID mungkin memiliki bentuk "monitoring-demo" atau "monitoring-demo-2349". Project ID terkadang secara biasa disebut sebagai nama proyek.
• Nomor project: ID numerik unik.

Setiap jenis resource yang dimonitor menyertakan label project_id, dengan representasi string untuk nomor project dari project yang memiliki resource tersebut dan data tentang resource tersebut.

Dalam kueri MQL, Anda menyebut label ini sebagai resource.project_id. Label resource.project_id memiliki nomor project dalam bentuk teks sebagai nilainya, tetapi MQL mengonversi nilai tersebut menjadi project ID dalam situasi tertentu.

Dalam kasus berikut, MQL memperlakukan nilai label resource.project_id sebagai project ID, bukan nomor project:

• Legenda untuk diagram menampilkan project ID, bukan nomor project untuk nilai label resource.project_id.

• Perbandingan kesetaraan nilai resource.project_id dengan literal string mengenali nomor project dan project ID. Misalnya, kedua hal berikut menampilkan nilai benar (true) untuk resource yang dimiliki oleh project ini:

  • resource.project_id == "monitoring-demo"
  • resource.project_id == "530310927541"

  Kasus ini berlaku untuk operator == dan != serta untuk bentuk fungsinya, eq() dan ne().

• Ekspresi reguler yang cocok pada label resource.project_id berfungsi dengan benar terhadap nomor project atau project ID. Misalnya, kedua ekspresi berikut menampilkan true untuk resource yang dimiliki oleh project ini:

  • resource.project_id =~ "monitoring-.*"
  • resource.project_id =~ ".*27541"

  Kasus ini berlaku untuk operator =~ dan !~, serta untuk formulir fungsi, re_full_match.

Untuk semua kasus lainnya, nilai sebenarnya dari label resource.project_id akan digunakan. Misalnya, concatenate("project-", resource.project_id) menghasilkan nilai project-530310927541, bukan project-monitoring-demo.

Rasio dan “efek tepi”

Secara umum, sebaiknya hitung rasio berdasarkan deret waktu yang dikumpulkan untuk satu jenis metrik, dengan menggunakan nilai label. Rasio yang dihitung pada dua jenis metrik yang berbeda mengalami anomali karena periode pengambilan sampel dan periode penyelarasan yang berbeda.

Misalnya, Anda memiliki dua jenis metrik yang berbeda, jumlah total RPC dan jumlah error RPC, dan Anda ingin menghitung rasio RPC jumlah error terhadap total RPC. RPC yang gagal dihitung dalam deret waktu dari kedua jenis metrik. Oleh karena itu, ada kemungkinan bahwa, saat Anda menyelaraskan deret waktu, RPC yang gagal tidak akan muncul dalam interval penyelarasan yang sama untuk kedua deret waktu. Perbedaan ini dapat terjadi karena beberapa alasan, termasuk:

• Karena ada dua deret waktu berbeda yang mencatat peristiwa yang sama, ada dua nilai penghitung dasar yang mengimplementasikan pengumpulan ini, dan keduanya tidak diperbarui secara atomik.
• Frekuensi sampling mungkin berbeda. Jika deret waktu disejajarkan dengan periode umum, jumlah untuk satu peristiwa mungkin muncul di interval penyelarasan yang berdekatan dalam deret waktu untuk metrik yang berbeda.

Perbedaan jumlah nilai dalam interval perataan yang sesuai dapat menyebabkan nilai rasio error/total yang tidak masuk akal seperti 1/0 atau 2/1.

Rasio angka yang lebih besar cenderung tidak menghasilkan nilai yang tidak masuk akal. Anda bisa mendapatkan jumlah yang lebih besar melalui agregasi, baik dengan menggunakan periode penyelarasan yang lebih panjang dari periode pengambilan sampel, atau dengan mengelompokkan data untuk label tertentu. Teknik ini meminimalkan efek perbedaan kecil dalam jumlah titik dalam interval tertentu. Artinya, selisih dua titik akan lebih signifikan jika jumlah titik yang diharapkan dalam suatu interval adalah 3 daripada jumlah yang diharapkan adalah 300.

Jika menggunakan jenis metrik bawaan, Anda mungkin tidak memiliki pilihan selain menghitung rasio di seluruh jenis metrik untuk mendapatkan nilai yang diperlukan.

Jika Anda mendesain metrik kustom yang mungkin menghitung hal yang sama—seperti RPC yang menampilkan status error—dalam dua metrik berbeda, pertimbangkan satu metrik yang mencakup setiap hitungan hanya sekali. Misalnya, Anda menghitung RPC dan ingin melacak rasio RPC yang gagal terhadap semua RPC. Untuk mengatasi masalah ini, buat satu jenis metrik untuk menghitung RPC, dan gunakan label untuk mencatat status pemanggilan, termasuk status "OK". Kemudian setiap nilai status, error atau "OK", dicatat dengan memperbarui satu penghitung untuk kasus tersebut.

Format tanggal MQL

MQL saat ini mendukung sejumlah format tanggal tertentu. Dalam kueri MQL, tanggal dinyatakan sebagai salah satu dari hal berikut:

• d'BASE_STRING'
• D'BASE_STRING'

BASE_STRING adalah string berbentuk 2010/06/23-19:32:15-07:00. Tanda hubung pertama (-), yang memisahkan tanggal dan waktu, dapat diganti dengan spasi. Pada komponen waktu, bagian dari waktu jam (19:32:15) atau penentu zona waktu (-07:00) dapat dihapus.

Contoh berikut adalah tanggal yang valid dalam kueri MQL:

• d'2010/06/23-19:32:15-07:00'
• d'2010/06/23 19:32:15-07:00'
• d'2010/06/23 19:32:15'
• D'2010/06/23 19:32'
• d'2010/06/23-19'
• D'2010/06/23 -07:00'

Tabel berikut mencantumkan tata bahasa untuk BASE_STRING:

Struktur	Arti
%Y/%m/%d	Tanggal
%Y/%m/%d %H %Y/%m/%d-%H	Tanggal, jam
%Y/%m/%d %H:%M %Y/%m/%d-%H:%M	Tanggal, jam, menit
%Y/%m/%d %H:%M:%S %Y/%m/%d-%H:%M:%S	Tanggal, jam, menit, detik
%Y/%m/%d %H:%M:%E*S %Y/%m/%d-%H:%M:%E*S	Tanggal, jam, menit, detik pecahan
%Y/%m/%d %Ez	Tanggal dengan zona waktu
%Y/%m/%d %H%Ez %Y/%m/%d-%H%Ez	Tanggal, jam, dengan zona waktu
%Y/%m/%d %H:%M%Ez %Y/%m/%d-%H:%M%Ez	Tanggal, jam, menit, dengan zona waktu
%Y/%m/%d %H:%M:%S%Ez %Y/%m/%d-%H:%M:%S%Ez	Tanggal, jam, menit, detik, dengan zona waktu
%Y/%m/%d %H:%M:%E*S%Ez %Y/%m/%d-%H:%M:%E*S%Ez	Tanggal, jam, menit, detik pecahan, dengan zona waktu

Panjang dan kompleksitas kueri

Kueri Monitoring Bahasa Kueri bisa jadi panjang dan rumit, tetapi bukan tanpa batas.

• Teks kueri, yang dienkode sebagai UTF-8, dibatasi hingga 10.000 byte.
• Kueri dibatasi hingga 2.000 konstruksi bahasa; yaitu, kompleksitas AST^† dibatasi hingga 2.000 node.

^† Hierarki sintaksis abstrak, atau AST, adalah representasi kode sumber—dalam hal ini, string kueri MQL—tempat node dalam hierarki memetakan ke struktur sintaksis dalam kode.

Makro MQL

Pratinjau

Produk atau fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum di Persyaratan Khusus Layanan. Produk dan fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

MQL menyertakan utilitas definisi makro. Anda dapat menggunakan makro MQL untuk mengganti operasi berulang, membuat kueri yang kompleks lebih mudah dibaca, dan mempermudah pengembangan kueri. Anda dapat menentukan makro untuk operasi tabel dan fungsi.

Definisi makro dimulai dengan kata kunci def.

Saat Anda mengonversi kueri menjadi formulir ketat, pemanggilan makro diganti dengan teks yang sesuai dan definisi makro akan dihapus.

Saat Anda menyimpan kueri diagram yang menyertakan makro, kueri tersebut dikonversi ke bentuk ketat, sehingga makro apa pun tidak dipertahankan. Saat Anda menyimpan kueri untuk kondisi dalam kebijakan pemberitahuan, kueri tersebut tidak dikonversi ke bentuk ketat, sehingga makro tetap dipertahankan.

Makro untuk operasi tabel

Anda dapat menulis makro untuk melakukan operasi tabel baru. Sintaksis umumnya terlihat seperti berikut:

def MACRO_NAME [MACRO_PARAMETER[, MACRO_PARAMETER]] = MACRO_BODY ;

Untuk memanggil makro, gunakan sintaksis berikut:

@MACRO_NAME [MACRO_ARG [, MACRO_ARG]]

Misalnya, anggaplah Anda menggunakan kueri berikut untuk mengambil data pemakaian CPU:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| every 1m
| group_by [zone], mean(val())

Baris pertama dapat diganti dengan makro berikut:

def my_fetch = fetch gce_instance::compute.googleapis.com/instance/cpu/utilization ;

Untuk memanggil makro dalam kueri, ganti fetch asli seperti berikut:

def my_fetch = fetch gce_instance::compute.googleapis.com/instance/cpu/utilization ;

@my_fetch
| every 1m
| group_by [zone], mean(val())

Anda dapat mengganti baris kedua dan ketiga dengan makro yang menggunakan argumen. Definisi makro mencantumkan parameter ke makro, dan dalam isi makro, mengacu pada parameter untuk makro sebagai $MACRO_PARAMETER. Misalnya, Anda dapat menentukan makro berikut:

def my_every time_arg = every $time_arg ;

def my_group label, aggr = group_by [$label], $aggr ;

Untuk memanggil makro ini dan memberikan argumen, tentukan argumen dalam daftar yang dipisahkan koma dalam pemanggilan makro. Berikut adalah kueri dengan semua makro yang ditentukan dan pemanggilannya:

def my_fetch = fetch gce_instance::compute.googleapis.com/instance/cpu/utilization ;
def my_every time_arg = every $time_arg ;
def my_group label, aggr = group_by [$label], $aggr ;

{@my_fetch}
| @my_every 1m
| @my_group zone, mean(val())

Makro tidak dipertahankan saat kueri dikonversi ke bentuk ketat. Misalnya, bentuk ketat kueri sebelumnya terlihat seperti berikut:

fetch gce_instance::compute.googleapis.com/instance/cpu/utilization
| align mean_aligner()
| every 1m
| group_by [resource.zone],
           [value_utilization_mean: mean(value.utilization)]

Makro untuk fungsi

Untuk fungsi MQL, tentukan parameter apa pun dalam daftar yang dipisahkan koma dalam tanda kurung. Tanda kurung membedakan makro fungsi dengan makro operasi tabel. Tanda kurung harus muncul dalam pemanggilan, meskipun tidak ada argumen. Makro tidak dipertahankan saat kueri dikonversi ke bentuk ketat.

def MACRO_NAME([MACRO_PARAMETER [, MACRO_PARAMETER]]) = MACRO_BODY ;

Misalnya, kueri berikut mengambil tabel untuk dua metrik, menggabungkan dua tabel menjadi satu dengan dua kolom nilai, dan menghitung rasio byte yang diterima terhadap total byte untuk kolom yang bernama received_percent:

{
  fetch k8s_pod :: kubernetes.io/pod/network/received_bytes_count ;
  fetch k8s_pod :: kubernetes.io/pod/network/sent_bytes_count
}
| join
| value [received_percent: val(0) * 100 / (val(0) + val(1))]

Anda dapat mengganti komputasi received_percent dengan makro seperti contoh berikut:

def recd_percent(recd, sent) = $recd * 100 / ($recd + $sent) ;

Untuk memanggil makro fungsi, gunakan sintaksis berikut:

@MACRO_NAME([MACRO_ARG[, MACRO_ARG]])

Saat memanggil makro fungsi tanpa argumen, Anda harus menentukan tanda kurung kosong untuk membedakan pemanggilan dari pemanggilan makro operasi tabel.

Contoh berikut menunjukkan kueri sebelumnya dengan makro untuk komputasi rasio:

def recd_percent(recd, sent) = $recd * 100 / ($recd + $sent) ;

{
  fetch k8s_pod :: kubernetes.io/pod/network/received_bytes_count ;
  fetch k8s_pod :: kubernetes.io/pod/network/sent_bytes_count
}
| join
| value [received_percent: @recd_percent(val(0), val(1))]

Kemampuan makro

Makro MQL adalah elemen sintaksis, berbeda dengan elemen tekstual seperti makro yang digunakan dalam preprocessor C. Perbedaan ini berarti bahwa isi makro MQL harus selalu berupa ekspresi yang valid secara sintaksis. Nilai ini mungkin tidak valid secara semantik, yang juga bergantung pada argumen makro dan lokasi tempat makro diperluas.

Karena makro MQL bersifat sintaksis, hanya ada sedikit batasan pada jenis ekspresi yang dapat diperluas. Makro sintaksis hanyalah cara lain untuk memanipulasi hierarki sintaksis abstrak. Contoh berikut menunjukkan beberapa hal yang dapat Anda lakukan dengan makro sintaksis:

# Abbreviating a column name.
def my_col() = instance_name;

# Map-valued macro.
def my_map(c) = [$c, @my_col()];

# Abbreviating a string.
def my_zone() = 'us-central.*';

# Abbreviating a filter expression.
def my_filter(f) = zone =~ @my_zone() && $f;

MQL juga mendukung penyambungan literal string implisit. Fitur ini dapat sangat berguna saat menulis kueri yang menyertakan nama metrik yang panjang. Jika literal string dan argumen makro, yang juga harus berupa literal string, muncul berdampingan dalam isi makro, perluasan makro akan menggabungkannya menjadi satu literal string.

Dalam contoh berikut, gce_instance adalah elemen leksikal BARE_NAME. Hal ini otomatis dipromosikan ke literal string yang berguna dalam membuat nama tabel:

# Builds a table name in domain 'd' with the suffix 'm'.
def my_table(d, m) = gce_instance::$d '/instance/' $m;

# Table name under the given domain.
def my_compute_table(m) = @my_table('compute.googleapis.com', $m);

Dengan menggabungkan semuanya, kueri berikut menggunakan semua makro yang telah ditentukan sebelumnya:

fetch @my_compute_table('cpu/utilization')
| filter @my_filter(instance_name =~ 'gke.*')
| group_by @my_map(zone)

Perhatikan bahwa argumen makro juga dapat berupa ekspresi arbitrer, asalkan sintaksisnya benar. Misalnya, my_filter makro dapat mengambil ekspresi Boolean seperti instance_name =~ 'gke.*' sebagai argumen pertamanya.

Operasi tabel singkat juga bisa sangat berguna, seperti yang ditunjukkan oleh kueri berikut:

# Calculate the ratio between compute metrics 'm1' and 'm2'.
def my_compute_ratio m1, m2 =
  { fetch @my_compute_table($m1); fetch @my_compute_table($m2) }
  | join | div;

# Use the table op macro to calculate the ratio between CPU utilization and
# the number of reserved cores per zone.
@my_compute_ratio 'cpu/utilization', 'cpu/reserved_cores' | group_by [zone]

Terakhir, makro fungsi dapat berperilaku seperti fungsi reguler; yaitu, makro fungsi memungkinkan promosi fungsi dengan kolom nilai atau kolom tabel input menjadi argumen pertama pada makro. Contoh berikut menunjukkan varian dari kueri sebelumnya yang menggunakan makro fungsi:

# Simple arithmetic macro.
def my_add_two(x) = $x + 2;

# Similar to previous query, but now using the new arithmetic macro with
# function argument promotion.
fetch @my_compute_table('cpu/utilization')
| filter @my_filter(instance_name =~ 'gke.*')
| group_by @my_map(zone), [.sum.@my_add_two]

Batasan

Fitur makro MQL tidak mendukung hal berikut:

• Penyusunan definisi makro: Anda tidak dapat menentukan makro dalam isi makro lain.
• Makro yang ditentukan secara rekursif. Tidak ada isi makro yang dapat mereferensikan makro apa pun, termasuk makro itu sendiri, yang belum sepenuhnya ditentukan.
• Penggunaan fungsi yang ditentukan makro sebagai operasi tabel.
• Penggunaan argumen makro sebagai nama fungsi atau operasi tabel.
• Preservasi makro saat kueri dikonversi ke bentuk ketat. Pemanggilan makro diganti dengan ekspresi yang sesuai, dan definisi makro dihapus.