Bahasa kueri Logging

Dokumen ini menjelaskan, secara umum, bahasa kueri Logging yang Anda gunakan untuk membuat kueri dan memfilter data Cloud Logging.

Untuk mengetahui informasi mendalam tentang desain bahasa kueri Logging, lihat spesifikasi formal API Google untuk pemfilteran.

Untuk contoh kueri umum yang mungkin ingin Anda gunakan, lihat Contoh kueri menggunakan Logs Explorer.

Ringkasan

Anda dapat menggunakan bahasa kueri Logging di Logs Explorer di konsolGoogle Cloud , Logging API, atau antarmuka command line. Anda dapat menggunakan bahasa kueri Logging untuk membuat kueri data dan menulis filter untuk membuat sink dan metrik berbasis log.

Kueri adalah ekspresi Boolean yang menentukan subset dari semua entri log dalam Google Cloud resource yang dipilih, seperti Google Cloud project atau folder.

Anda dapat membuat kueri berdasarkan LogEntry kolom yang diindeks menggunakan operator logis AND dan OR. Dengan menggunakan kolom resource.type dalam contoh berikut, tata bahasa bahasa kueri Logging akan terlihat seperti ini:

  • Pembatasan sederhana: resource.type = "k8s_cluster"

  • Pembatasan konjungtif: resource.type = "k8s_cluster" AND severity = "ERROR"

  • Pembatasan disjungtif: resource.type = "k8s_cluster" OR resource.type = "gce_instance"

    • Atau: resource.type = ("k8s_cluster" OR "gce_instance")

  • Ekspresi konjungtif/disjungtif kompleks: resource.type = "k8s_cluster" AND (severity = "ERROR" OR "error")

Berikut adalah contoh kueri:

resource.type = "gce_instance" AND
severity >= "ERROR" AND
NOT textPayload:robot

Kueri ini cocok dengan entri log dari Compute Engine yang memiliki nilai tingkat keparahan minimal ERROR dan kolom textPayload-nya tidak berisi string robot di mana pun di dalamnya. Perbandingan string tidak peka huruf besar/kecil. Nama resource, severity, dan textPayload ditentukan dalam jenis LogEntry.

Notasi sintaksis

Bagian berikut memberikan ringkasan sintaksis bahasa kueri Logging, dan membahas secara mendetail cara menyusun kueri dan cara pencocokan dilakukan. Beberapa contoh menggunakan komentar untuk memberikan teks penjelasan.

Perhatikan hal berikut:

  • Panjang kueri tidak boleh melebihi 20.000 karakter.

  • Bahasa kueri Logging tidak peka huruf besar/kecil, kecuali ekspresi reguler dan operator logis, seperti AND dan OR. Operator logika harus ditulis dengan huruf kapital.

Ringkasan sintaksis

Sintaksis bahasa kueri Logging dapat dipikirkan dalam hal kueri dan perbandingan.

Kueri adalah string yang berisi ekspresi:

expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }

Perbandingan dapat berupa satu nilai atau ekspresi Boolean:

"The cat in the hat"
resource.type = "k8s_cluster"

Baris pertama adalah contoh perbandingan yang merupakan satu nilai. Jenis perbandingan ini merupakan pembatasan global. Setiap kolom entri log dibandingkan dengan nilai secara implisit menggunakan operator has. Untuk contoh ini, jika ada kolom dalam LogEntry, atau jika payload-nya, berisi frasa "The cat in the hat", maka perbandingan berhasil.

Baris kedua adalah contoh perbandingan yang merupakan ekspresi Boolean dari bentuk [FIELD_NAME] [OP] [VALUE]. Perbandingan memiliki tiga komponen:

  • [FIELD_NAME] adalah kolom dalam entri log. Contoh, resource.type.

  • [OP] adalah operator perbandingan. Contoh, =.

  • [VALUE] adalah angka, string, fungsi, atau ekspresi dalam tanda kurung. Contoh, "k8s_cluster". Untuk nilai null JSON, gunakan NULL_VALUE.

Operator Boolean

Operator Boolean AND dan OR adalah operator short-circuit. Operator NOT memiliki prioritas tertinggi, diikuti oleh OR dan AND dalam urutan tersebut. Misalnya, dua ekspresi berikut setara:

"a" OR NOT "b" AND NOT "c" OR "d"
("a" OR (NOT "b")) AND ((NOT "c") OR "d")

Anda dapat menghilangkan operator AND di antara perbandingan. Anda juga dapat mengganti operator NOT dengan operator - (minus). Misalnya, dua kueri berikut sama:

a="b" AND c="d" AND NOT e="f"
a="b" c="d" -e="f"

Dokumentasi ini selalu menggunakan AND dan NOT.

Untuk semua filter kecuali filter yang digunakan oleh tampilan log, Anda dapat menggunakan operator AND, OR, dan NOT. Tampilan log hanya mendukung operasi AND dan NOT.

Untuk menggabungkan aturan AND dan OR dalam ekspresi yang sama, Anda harus menyusun aturan menggunakan tanda kurung. Jika Anda tidak menggunakan tanda kurung, kueri Anda mungkin tidak berfungsi sebagaimana mestinya.

Operator Boolean harus selalu ditulis dengan huruf kapital. and, or, dan not huruf kecil diuraikan sebagai istilah penelusuran.

Perbandingan

Perbandingan memiliki bentuk berikut:

[FIELD_NAME] [OP] [VALUE]

Perbandingan memiliki tiga komponen:

  • [FIELD_NAME]: adalah ID jalur kolom dari kolom dalam entri log. Berikut adalah contoh pengidentifikasi tersebut:

    resource.type
resource.labels.zone
resource.labels.project_id
insertId
jsonPayload.httpRequest.protocol
labels."compute.googleapis.com/resource_id"

    Jika komponen ID jalur kolom memiliki karakter khusus, komponen tersebut harus diapit tanda petik ganda. Misalnya, compute.googleapis.com/resource_id harus diapit tanda kutip ganda karena berisi garis miring /.

    Untuk mengetahui detailnya, lihat ID jalur kolom dalam dokumen ini.

  • [OP]: adalah operator perbandingan, salah satu dari berikut:

    =           -- equal
!=          -- not equal
> < >= <=   -- numeric ordering
:           -- "has" matches any substring in the log entry field
=~          -- regular expression search for a pattern
!~          -- regular expression search not for a pattern

Untuk mempelajari cara menelusuri entri log menggunakan ekspresi reguler, lihat Menggunakan ekspresi reguler.

  • [VALUE]: adalah angka, string, fungsi, atau ekspresi dalam tanda kurung. String digunakan untuk merepresentasikan teks arbitrer, ditambah nilai Boolean, enumerasi, dan string byte. [VALUE] dikonversi ke jenis kolom sebelum perbandingan. Untuk nilai null JSON, gunakan NULL_VALUE.

Untuk memfilter nilai null JSON, gunakan sintaksis berikut:

jsonPayload.field = NULL_VALUE      -- includes "field" with null value
NOT jsonPayload.field = NULL_VALUE  -- excludes "field" with null value

Jika [VALUE] adalah kombinasi Boolean perbandingan dalam tanda kurung, maka nama kolom dan operator perbandingan diterapkan ke setiap elemen. Contoh:

jsonPayload.cat = ("longhair" OR "shorthair")
jsonPayload.animal : ("nice" AND "pet")

Perbandingan pertama memeriksa apakah kolom cat memiliki nilai "longhair" atau "shorthair". Pemeriksaan kedua memastikan bahwa nilai kolom animal berisi kedua kata "nice" dan "pet", dalam urutan apa pun.

ID jalur kolom

Semua entri log adalah instance jenis LogEntry. ID yang (atau memulai) sisi kiri perbandingan harus berupa kolom yang ditentukan dalam jenis LogEntry. Untuk mengetahui detail tentang kemungkinan ID dan nilainya, lihat jenis LogEntry.

Berikut adalah daftar kolom entri log saat ini. Setiap kolom diikuti dengan tingkat nama berikutnya untuk kolom tersebut, jika ada:

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
  • insertId
  • jsonPayload { variable }
  • labels { variable }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, variable }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

Berikut adalah contoh ID jalur kolom yang dapat Anda gunakan dalam perbandingan:

  • resource.type: Jika ID jalur pertama Anda adalah resource, maka ID berikutnya harus berupa kolom dalam jenis MonitoredResource.

  • httpRequest.latency: Jika ID jalur pertama Anda adalah httpRequest, maka ID berikutnya harus berupa kolom dalam jenis HttpRequest.

  • labels.[KEY] Jika ID jalur pertama Anda adalah labels, maka ID berikutnya, [KEY], harus berupa salah satu kunci dari pasangan nilai kunci yang muncul di kolom labels.

  • logName: Karena kolom logName adalah string, Anda tidak dapat mengikutinya dengan nama subkolom apa pun.

Saat membuat kueri kolom map atau struct, Anda harus mempertahankan format dan huruf besar/kecil kunci dalam ekspresi.

Misalnya, jsonPayload adalah kolom struct, sehingga nama kolom yang berada di dalam jsonPayload seperti jsonPayload.end_time berbeda dari jsonPayload.endTime. Demikian pula, untuk kolom peta seperti labels, kunci label labels.env_name berbeda dengan labels.envName. Sebaliknya, saat mengirim kueri ke kolom buffer protokol reguler protoPayload, Anda tidak perlu mempertahankan kapitalisasi.

Untuk mengetahui informasi tentang jenis kolom LogEntry, lihat referensi google.logging.v2.

Karakter khusus

Jika kolom LogEntry berisi karakter khusus, kolom log harus diberi tanda petik. Contoh:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

Untuk mengetahui daftar karakter khusus, lihat bagian string di Nilai dan konversi.

Untuk mengetahui informasi selengkapnya tentang penggunaan ID jalur kolom yang mereferensikan objek atau array, lihat Jenis objek dan array dalam dokumen ini.

Jenis resource yang dipantau

Untuk kueri yang lebih cepat, tentukan jenis resource yang dipantau. Untuk mengetahui daftar jenis resource, lihat Jenis resource yang dimonitor.

Misalnya, VM Compute Engine menggunakan jenis resource gce_instance dan instance Amazon EC2 menggunakan aws_ec2_instance. Contoh berikut menunjukkan cara membatasi kueri Anda ke kedua jenis VM:

resource.type = ("gce_instance" OR "aws_ec2_instance")

Nilai jenis resource yang dimonitor dalam log diindeks. Menggunakan kecocokan substring untuknya akan menghasilkan kueri yang lebih lambat.

Kolom tidak ada

Jika Anda menggunakan nama kolom dalam kueri, dan kolom tersebut tidak muncul dalam entri log, maka kolom tersebut tidak ada, tidak ditentukan, atau default:

  • Jika kolom adalah bagian dari payload entri log (jsonPayload atau protoPayload), atau jika ada di label di bagian labels entri log, maka kolom tersebut tidak ada. Menggunakan kolom yang tidak ada tidak akan menampilkan error, tetapi semua perbandingan yang menggunakan kolom yang tidak ada akan gagal tanpa pemberitahuan.

    Contoh: jsonPayload.nearest_store, protoPayload.name.nickname

  • Jika kolom ditentukan dalam jenis LogEntry, maka kolom tersebut akan ditetapkan secara default. Perbandingan dilakukan seolah-olah kolom ada dan memiliki nilai defaultnya.

    Contoh: httpRequest.remoteIp, trace, operation.producer

  • Jika tidak, kolom akan tidak ditentukan, yang merupakan error yang terdeteksi sebelum kueri digunakan.

    Contoh: thud, operation.thud, textPayload.thud

Untuk menguji apakah kolom yang tidak ada atau memiliki nilai default ada tanpa menguji nilai tertentu dalam kolom, gunakan perbandingan :*. Misalnya, perbandingan berikut berhasil jika kolom operation.id ada secara eksplisit dalam entri log:

operation.id:*

Perhatikan perilaku kueri berikut:

  • Jika Anda menggunakan operator Boolean NOT pada kolom yang tidak ada, hasilnya adalah TRUE:

    -- Returns TRUE
NOT missingField=foo

  • Saat Anda menggunakan operator perbandingan tidak sama dengan != pada kolom yang tidak ada, hasilnya adalah FALSE:

    -- Returns FALSE
missingField!=foo

Jenis objek dan array

Setiap kolom entri log dapat menyimpan skalar, objek, atau array.

  • Kolom skalar menyimpan satu nilai, seperti 174.4 atau -1. string juga dianggap sebagai skalar. Kolom yang dapat dikonversi ke (atau dari) string, seperti Duration dan Timestamp juga merupakan jenis skalar.

  • Jenis objek menyimpan kumpulan nilai bernama, seperti nilai JSON berikut:

    {"age": 24, "height": 67}

    Anda dapat merujuk ke nilai di dalam objek. Misalnya, jika jsonPayload.x berisi nilai sebelumnya, maka jsonPayload.x.age akan memiliki nilai 24.

  • Kolom array menyimpan daftar nilai—semuanya memiliki jenis yang sama. Misalnya, kolom yang menyimpan pengukuran mungkin memiliki array angka:

    {8.5, 9, 6}

    Saat perbandingan dilakukan dan [FIELD_NAME] adalah kolom array, setiap anggota array dibandingkan dengan [VALUE] dan hasilnya digabungkan menggunakan operator OR. Misalnya, jika jsonPayload.shoeSize adalah kolom array yang menyimpan {8.5, 9, 6}, perbandingannya:

    jsonPayload.shoeSize < 7

    setara dengan:

    8.5 < 7 OR 9 < 7 OR 6 < 7

    Dalam contoh ini, perbandingan keseluruhan bernilai berhasil.

Nilai dan konversi

Langkah pertama dalam mengevaluasi perbandingan adalah mengonversi nilai sisi kanan ke jenis kolom entri log. Jenis kolom skalar diizinkan dalam perbandingan, bersama dengan dua jenis tambahan yang nilainya direpresentasikan sebagai string: Duration dan Timestamp. Untuk daftar jenis skalar, lihat daftar jenis buffer protokol skalar. Tabel berikut menjelaskan nilai yang dapat dikonversi ke jenis kolom log:

Jenis kolom Nilai kueri yang diizinkan
bool

"True" atau "false" dalam huruf besar atau kecil. Contoh: "Benar", "benar"
bytes

String yang berisi urutan byte apa pun. Contoh: "\377\377".
Duration

String yang berisi angka desimal bertanda yang diikuti oleh salah satu satuan "ns", "us", "ms", "s", "m", atau "h". Durasi akurat hingga nanodetik. Contoh: "3.2s".
enum

Nama literal jenis enumerasi, tidak peka huruf besar/kecil. Contoh: "WARNING", yang merupakan nilai jenis LogSeverity.
double

Angka apa pun, dengan atau tanpa tanda dan bagian eksponen, atau string nilai khusus "NaN", "-Infinity", dan "Infinity" (dengan atau tanpa huruf kapital). Contoh: "-3.2e-8", "nan".
intNN

Setiap bilangan bulat bertanda yang tidak melebihi ukuran jenis. Contoh: "-3".
string

String apa pun yang berisi teks berenkode UTF-8 atau 7-bit ASCII. Tanda kutip yang disematkan harus di-escape dengan garis miring terbalik.

Nilai string harus diapit tanda petik ganda untuk meng-escape karakter khusus berikut:

  • String yang dimulai dengan + (plus), - (minus), atau . (titik).

  • String dengan ~ (tilde), = (sama dengan), () (tanda kurung), : (titik dua), > (lebih besar dari), < (lebih kecil dari), , (koma), . (titik), atau * (tanda bintang).

  • Urutan escape apa pun, misalnya \t.
Timestamp

String dalam format RFC 3339 atau ISO 8601. Contoh&colon; "2024-08-02T15&colon;01&colon;23.045Z" (RFC 3339), "2024-08-02" (ISO 8601). Dalam ekspresi kueri, stempel waktu dalam format RFC 3339 dapat menentukan zona waktu dengan "Z" atau ±hh:mm. Stempel waktu ditampilkan dengan akurasi nanodetik.
uintNN

Setiap bilangan bulat tidak bertanda yang tidak melebihi ukuran jenis. Contoh: "1234".

Jika upaya konversi gagal, perbandingan akan gagal.

Saat konversi memerlukan string, Anda juga dapat menggunakan angka atau teks tanpa tanda petik jika tidak berisi karakter khusus seperti spasi dan operator. Demikian pula, saat konversi memerlukan angka, Anda dapat menggunakan string yang isinya adalah angka.

Jenis intNN dan uintNN merepresentasikan jenis bilangan bulat dengan berbagai ukuran, seperti int32 dan uint64. Saat menulis nilai yang akan dikonversi ke jenis bilangan bulat 64-bit, Anda menulis nilai sebagai string, seperti "9223372036854775807".

Jenis kolom log

Berikut cara jenis kolom entri log ditentukan:

  • Kolom log yang ditentukan dalam jenis LogEntry, dan dalam jenis komponen adalah kolom buffer protokol. Kolom buffer protokol memiliki jenis eksplisit.

  • Kolom log yang merupakan bagian dari objek protoPayload juga merupakan kolom buffer protokol dan memiliki jenis eksplisit. Nama jenis buffer protokol disimpan di kolom "@type" dari protoPayload. Untuk mengetahui informasi selengkapnya, lihat pemetaan JSON.

    Saat Anda memfilter kolom yang terkait dengan jenis pesan Any, kolom value akan otomatis dilalui. Oleh karena itu, jangan sertakan dalam kueri. Untuk mengetahui informasi selengkapnya, lihat Pemecahan masalah.

  • Kolom log di dalam jsonPayload memiliki jenis yang disimpulkan dari nilai kolom saat entri log diterima:

    • Kolom yang nilainya adalah angka tanpa tanda petik memiliki jenis double.
    • Kolom yang nilainya true atau false memiliki jenis bool.
    • Kolom yang nilainya berupa string memiliki jenis string.

    Bilangan bulat panjang (64-bit) disimpan di kolom string, karena tidak dapat direpresentasikan secara tepat sebagai nilai double.

  • Jenis Duration dan Timestamp hanya dikenali di kolom buffer protokol. Di tempat lain, nilai tersebut disimpan dalam kolom string.

Komentar

Komentar dimulai dengan dua tanda hubung (--), dan teks apa pun setelah tanda hubung akan diabaikan hingga akhir baris. Komentar dapat ditempatkan di awal filter, di antara istilah, dan di akhir filter.

Anda dapat menggunakan komentar untuk kasus berikut:

  • Untuk menganotasi filter kompleks dengan informasi tentang fungsi klausa:

     -- All of our target users are emitted by Compute Engine instances.
 resource.type = "gce_instance"
 -- Looking for logs from "alex".
 jsonPayload.targetUser = "alex"

  • Untuk mengaktifkan atau menonaktifkan klausa dengan cepat dengan menambahkan atau menghapus awalan komentar:

     resource.type = "gce_instance"
 -- jsonPayload.targetUser = "alex"
 jsonPayload.targetUser = "kiran"
 -- jsonPayload.targetUser = "sasha"

Operator perbandingan

Arti operator kesetaraan (=, !=) dan ketidaksetaraan (<, <=, >, >=) bergantung pada jenis nama kolom di sebelah kiri yang mendasarinya.

  • Semua jenis numerik: Persamaan dan ketidaksamaan memiliki arti normal untuk angka.
  • bool: Kesamaan berarti nilai Boolean yang sama. Ketidaksetaraan ditentukan oleh true>false.
  • enum: Persamaan berarti nilai enumerasi yang sama. Ketidaksetaraan menggunakan nilai numerik pokok dari literal enumerasi.
  • Duration: Persamaan berarti durasi yang sama. Ketidaksetaraan didasarkan pada durasi. Contoh: sebagai durasi, "1s">"999ms".
  • Timestamp: Kesetaraan berarti saat yang sama dalam waktu. Jika a dan b adalah nilai Timestamp, a < b berarti a lebih awal daripada b.
  • bytes: Operan dibandingkan byte demi byte, dari kiri ke kanan.
  • string: Perbandingan mengabaikan huruf besar/kecil. Secara khusus, kedua operand dinormalisasi terlebih dahulu menggunakan normalisasi Unicode NFKC_CF, lalu menggunakan perbandingan leksikografis. Namun, penelusuran ekspresi reguler tidak dinormalisasi. Untuk mengetahui informasi selengkapnya tentang cara menelusuri entri log menggunakan ekspresi reguler, lihat Menggunakan ekspresi reguler.

Operator substring (:) berlaku untuk string dan bytes, dan ditangani seperti kesetaraan, kecuali operand sisi kanan hanya perlu sama dengan beberapa bagian kolom sisi kiri. Pencocokan substring pada kolom yang diindeks tidak memanfaatkan indeks log.

Pembatasan global

Jika perbandingan terdiri dari satu nilai, nilai tersebut disebut pembatasan global. Pencatatan log menggunakan operator has (:) untuk menentukan apakah ada kolom dalam entri log, atau apakah payload-nya, berisi pembatasan global. Jika ya, perbandingan akan berhasil.

Kueri paling sederhana yang ditulis dalam hal pembatasan global adalah satu nilai:

"The Cat in The Hat"

Anda dapat menggabungkan pembatasan global menggunakan operator AND dan OR untuk kueri yang lebih menarik. Misalnya, jika Anda ingin menampilkan semua entri log yang memiliki kolom yang berisi cat dan kolom yang berisi hat atau bat, tulis kueri sebagai:

("cat" AND ("hat" OR "bat"))

Dalam hal ini, ada tiga batasan global: cat, hat, dan bat. Batasan global ini diterapkan secara terpisah dan hasilnya digabungkan, sama seperti jika ekspresi ditulis tanpa tanda kurung.

Pembatasan global adalah salah satu cara untuk membuat kueri log Anda untuk nilai tertentu. Misalnya, jika Anda mencari entri yang berisi penyebutan GCE_OPERATION_DONE di log aktivitas Anda, Anda dapat menggunakan kueri berikut:

logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log" AND
"GCE_OPERATION_DONE"

Daripada menggunakan batasan global, yang dapat memperlambat, sebaiknya gunakan fungsi SEARCH bawaan dan kueri kolom yang diindeks. Untuk mengetahui informasi selengkapnya, lihat Menemukan entri log dengan cepat dalam dokumen ini.

Functions

Anda dapat menggunakan fungsi bawaan sebagai batasan global dalam kueri:

function = identifier ( [ argument { , argument } ] )

dengan argument adalah nilai, nama kolom, atau ekspresi dalam tanda kurung. Fungsi ini dijelaskan di bagian berikut.

log_id

Fungsi log_id berguna saat membuat tampilan log kustom di bucket log yang berisi entri log dari banyak Google Cloud project, folder, atau organisasi.

Satu-satunya argumen untuk fungsi log_id adalah ID log yang tidak di-URL-encode:

log_id(non-URL-encoded log ID)

Misalnya, kueri berikut menampilkan semua log audit aktivitas:

log_id("cloudaudit.googleapis.com/activity")

Dalam kueri sebelumnya, argumen hanya terdiri dari karakter alfanumerik dan karakter khusus, (/, _, -, .).

transmisikan

Fungsi cast menerima dua parameter; kolom LogEntry yang akan di-casting, dan jenis data yang akan dikonversi menjadi kolom:

cast([FIELD], [TYPE][, OPTION])

Parameter ekspresi sebelumnya ditentukan sebagai berikut:

  • [FIELD]: Nama kolom dalam entri log, seperti logName atau jsonPayload.a_field.

  • [TYPE]: Jenis data, seperti STRING, INT64, FLOAT64, BOOL.

    • TIMESTAMP, atau DURATION: Beberapa jenis data menawarkan opsi tambahan, seperti menentukan zona waktu Database Zona Waktu IANA untuk jenis data TIMESTAMP.

Misalnya, kueri berikut melakukan transmisi kolom timestamp ke STRING dan menentukan zona waktu America/New_York:

cast(timestamp, STRING, TIME_ZONE("America/New_York")) =~ "^2025-04-02.*"

regexp_extract

Gunakan fungsi regexp_extract untuk menemukan substring pertama yang cocok dengan ekspresi reguler:

REGEXP_EXTRACT([FIELD], [REGULAR_EXPRESSION])

Dalam ekspresi sebelumnya, kolom ditentukan sebagai berikut:

  • [FIELD]: Nama kolom dalam entri log, seperti logName atau jsonPayload.a_field.
  • [REGULAR_EXPRESSION]: Ekspresi reguler RE2 yang harus berisi satu grup tangkapan ((...)). Grup non-penangkapan (?:...) harus digunakan jika pengelompokan tambahan diperlukan untuk ekspresi reguler. Beberapa grup pengambilan atau tidak ada grup pengambilan akan menghasilkan error.

Anda dapat menggabungkan fungsi cast dan regexp_extract:

CAST(REGEXP_EXTRACT(CAST(timestamp, STRING), "\\d+:\\d+:(\\d+)"), INT64) < 30

Contoh sebelumnya mentransmisikan kolom timestamp sebagai string. Ekspresi reguler mengambil nilai kolom detik dari string timestamp, lalu mentransformasikannya menjadi bilangan bulat untuk melakukan perbandingan numerik. Hasil kueri mencantumkan entri log saat kolom detik stempel waktunya kurang dari 30.

sumber

Fungsi source mencocokkan entri log dari resource tertentu dalam hierarki organisasi, folder, dan project Google Cloud .

Fungsi source tidak cocok dengan resource turunan. Misalnya, menggunakan source(folders/folder_123) mencocokkan log dari resource folder_123, dan bukan log dari resource project Google Cloud dalam folder_123.

Untuk membuat kueri log di tingkat resource tertentu, gunakan sintaksis berikut:

source(RESOURCE_TYPE/RESOURCE_ID)
Resource Contoh kueri
Organisasi source(organizations/ORGANIZATION_ID)
Folder source(folders/FOLDER_ID)
Google Cloud project source(projects/PROJECT_ID)

contoh

Fungsi sample memilih sebagian kecil dari jumlah total entri log:

sample([FIELD], [FRACTION])

[FIELD] adalah nama kolom dalam entri log, seperti logName atau jsonPayload.a_field. Nilai kolom menentukan apakah entri log ada dalam sampel. Jenis kolom harus berupa nilai string atau numerik. Menetapkan [FIELD] ke insertId adalah pilihan yang baik, karena setiap entri log memiliki nilai yang berbeda untuk kolom tersebut.

[FRACTION] adalah fraksi entri log yang memiliki nilai untuk [FIELD] yang akan disertakan. Nilai ini adalah angka yang lebih besar dari 0,0 dan tidak lebih besar dari 1,0. Misalnya, jika Anda menentukan 0.01, maka sampel berisi sekitar satu persen dari semua entri log yang memiliki nilai untuk [FIELD]. Jika [FRACTION] adalah 1, semua entri log yang memiliki nilai untuk [FIELD] akan dipilih.

Contoh: Kueri berikut menampilkan 25 persen entri log dari log syslog:

logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)

Detail: Algoritma deterministik, berdasarkan hashing, digunakan untuk menentukan apakah entri log disertakan atau dikecualikan dari sampel. Akurasi sampel yang dihasilkan bergantung pada distribusi nilai yang di-hash. Jika nilai yang di-hash tidak terdistribusi secara merata, sampel yang dihasilkan dapat miring. Dalam kasus terburuk, jika [FIELD] selalu berisi nilai yang sama, sampel yang dihasilkan akan berisi [FRACTION] dari semua entri log atau tidak ada entri log.

Jika [FIELD] muncul dalam entri log, maka:

  • Hash nilai dihitung.
  • Nilai yang di-hash, yang berupa angka, dibagi dengan nilai yang di-hash maksimum yang mungkin.
  • Jika pecahan yang dihasilkan kurang dari atau sama dengan [FRACTION], entri log disertakan dalam sampel; jika tidak, entri log dikecualikan dari sampel.

Jika [FIELD] tidak muncul dalam entri log, maka:

  • Jika [FIELD] adalah bagian dari payload entri log atau bagian labels, entri log tidak dipilih untuk sampel, meskipun [FRACTION] adalah 1.
  • Jika tidak, entri log diperlakukan seolah-olah [FIELD] ada di entri log dan nilai [FIELD] adalah nilai default. Nilai default ditentukan oleh jenis LogEntry. Untuk mengetahui informasi selengkapnya tentang kolom yang tidak ada dan kolom default, lihat Kolom yang tidak ada dalam dokumen ini.

Untuk mengecualikan entri log dengan kolom default dari sampel, gunakan operator field-exists, :*. Kueri berikut menghasilkan sampel 1 persen dari entri log yang telah secara eksplisit memberikan nilai untuk field:

field:* AND sample(field, 0.01)

ip_in_net

Fungsi ip_in_net menentukan apakah alamat IP dalam entri log tercakup dalam subnet. Anda dapat menggunakan ini untuk mengetahui apakah permintaan berasal dari sumber internal atau eksternal. Contoh:

ip_in_net([FIELD], [SUBNET])

[FIELD] adalah kolom bernilai string dalam entri log yang berisi alamat IP atau rentang. Kolom dapat berulang, dalam hal ini hanya salah satu kolom berulang yang harus memiliki alamat atau rentang yang tercakup dalam subnet.

[SUBNET] adalah konstanta string untuk alamat atau rentang IP. Terjadi error jika [SUBNET] bukan alamat atau rentang IP yang sah, seperti yang dijelaskan nanti di bagian ini.

Contoh: Kueri berikut menguji alamat IP dalam payload entri log dari log my_log:

logName = "projects/my_project/logs/my_log" AND
ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")

Detail: Jika, dalam entri log, [FIELD] tidak ada, ditetapkan secara default, atau tidak berisi alamat atau rentang IP yang sah, fungsi akan menampilkan nilai salah (false). Untuk mengetahui informasi selengkapnya tentang kolom yang tidak ada dan kolom default, lihat Kolom yang tidak ada dalam dokumen ini.

Berikut contoh alamat dan rentang IP yang didukung:

  • IPv4: 10.1.2.3
  • Subnet IPv4: 10.1.2.0/24
  • CIDR IPv6: 1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • Subnet IPv6 CIDR: 1:2::/48

SEARCH fungsi

Anda dapat menggunakan fungsi SEARCH bawaan untuk menemukan string dalam data log:

SEARCH([query])
SEARCH([field], [query])

Kedua bentuk fungsi SEARCH berisi argumen query, yang harus diformat sebagai literal string. Dalam formulir pertama, seluruh entri log akan dicari. Dalam formulir kedua, Anda menentukan kolom dalam entri log yang akan ditelusuri.

Anda harus menentukan kolom query. Jika kolom ini tidak ditentukan, pesan error akan ditampilkan.

Saat fungsi SEARCH diproses, string query diproses oleh penganalisis teks yang membagi string menjadi token. Cloud Logging selalu melakukan perbandingan yang tidak peka huruf besar/kecil, bahkan untuk token yang diapit dengan tanda petik terbalik. Perilaku ini berbeda dengan BigQuery, yang mempertahankan huruf besar/kecil dalam token yang diapit dengan tanda petik terbalik. Untuk mengetahui informasi tentang aturan penganalisis, lihat dokumen BigQuery Aturan penganalisis teks.

Saat membuat penelusuran, pertimbangkan hal berikut:

  • Token tidak peka huruf besar/kecil. Fungsi berikut menghasilkan hasil yang sama:

    SEARCH("world")
SEARCH("World")

    Fungsi sebelumnya cocok dengan entri log saat satu kolom berisi token "world". Karena SEARCH melakukan pencocokan persis dan bukan pencocokan substring, fungsi sebelumnya tidak cocok dengan kolom yang nilainya adalah "worldwide".

  • Jika Anda tidak menentukan kolom yang akan ditelusuri, fungsi SEARCH akan mencocokkan entri log jika entri log tersebut berisi semua token. Namun, urutan token tidak penting dan token tidak harus ditemukan di kolom yang sama dalam entri log.

    Fungsi berikut menghasilkan hasil yang sama, dan cocok dengan entri log yang berisi token "hello" dan "world":

    SEARCH("hello world")
SEARCH("World hello")

  • Jika Anda menentukan kolom yang akan ditelusuri, fungsi SEARCH hanya akan menelusuri kolom tersebut. Kecocokan terjadi saat kolom tersebut berisi semua token; namun, urutan token tidak menjadi masalah.

    Fungsi berikut menghasilkan kecocokan hanya jika kolom textPayload berisi token "hello" dan "world":

    SEARCH(textPayload, "hello world")

  • Untuk menerapkan pencocokan persis yang tidak peka huruf besar/kecil pada frasa, tutup frasa dalam tanda petik terbalik. Misalnya, fungsi berikut cocok dengan string "hello world":

    SEARCH("`hello world`")
SEARCH("`Hello World`")
SEARCH("`HELLO WORLD`")

    Karena tanda petik terbalik digunakan dalam fungsi berikut, tanda petik terbalik akan menghasilkan hasil yang berbeda:

    SEARCH("`hello world`")
SEARCH("`world hello`")

Bahasa kueri Logging mendukung berbagai cara yang dapat Anda gunakan untuk menelusuri data log. Saat menelusuri string, lebih efisien menggunakan fungsi SEARCH daripada melakukan penelusuran global atau penelusuran substring. Namun, Anda tidak dapat menggunakan fungsi SEARCH untuk mencocokkan kolom non-teks. Untuk panduan tentang cara melakukan operasi penelusuran, lihat Meminimalkan penelusuran global dan substring.

Menelusuri menurut waktu

Di antarmuka, Anda dapat menetapkan batas tertentu pada tanggal dan waktu entri log yang akan ditampilkan. Misalnya, jika Anda menambahkan kondisi berikut ke kueri, panel hasil akan menampilkan entri log persis dalam periode 30 menit yang ditunjukkan dan Anda tidak akan dapat men-scroll di luar rentang tanggal tersebut:

timestamp >= "2023-11-29T23:00:00Z"
timestamp <= "2023-11-29T23:30:00Z"

Saat menulis kueri dengan stempel waktu, Anda harus menggunakan tanggal dan waktu dalam format yang ditunjukkan sebelumnya.

Anda juga dapat menelusuri entri log menggunakan pintasan timestamp. Misalnya, Anda dapat memasukkan tanggal dengan operator perbandingan untuk mendapatkan semua entri log setelah hari tertentu:

timestamp > "2023-11-29"

Menggunakan ekspresi reguler

Anda dapat menggunakan ekspresi reguler untuk membuat kueri dan membuat filter untuk tujuan, metrik, dan di mana pun filter log digunakan. Misalnya, Anda dapat menggunakan ekspresi reguler di Logs Explorer dan dengan Google Cloud CLI.

Ekspresi reguler adalah urutan karakter yang menentukan penelusuran. Bahasa kueri Logging menggunakan sintaksis RE2. Untuk penjelasan lengkap tentang sintaksis RE2, lihat wiki RE2 di GitHub.

Kueri ekspresi reguler memiliki karakteristik berikut:

  • Hanya kolom jenis string yang dapat dicocokkan dengan ekspresi reguler.

  • Normalisasi string tidak dilakukan; misalnya, kubernetes tidak dianggap sama dengan KUBERNETES. Untuk mengetahui informasi selengkapnya, lihat bagian Operator perbandingan.

  • Kueri peka huruf besar/kecil dan tidak ditambatkan secara default.

  • Operator boolean dapat digunakan di antara beberapa ekspresi reguler di sisi kanan operator perbandingan ekspresi reguler, =~ dan !~.

Kueri ekspresi reguler memiliki struktur berikut:

Mencocokkan pola:

jsonPayload.message =~ "regular expression pattern"

Tidak cocok dengan pola:

jsonPayload.message !~ "regular expression pattern"

=~ dan !~ mengubah kueri menjadi kueri ekspresi reguler, dan pola yang ingin Anda cocokkan harus berada dalam tanda petik ganda. Untuk membuat kueri pola yang berisi tanda petik ganda, lakukan escape menggunakan garis miring terbalik.

Contoh kueri log menggunakan ekspresi reguler

Jenis kueri Contoh
Kueri standar sourceLocation.file =~ "foo"
Kueri dengan penelusuran yang tidak peka huruf besar/kecil labels.subnetwork_name =~ "(?i)foo"
Kueri yang berisi tanda petik jsonPayload.message =~ "field1=\"bar.*\""
Membuat kueri menggunakan boolean or labels.pod_name =~ "(foo|bar)"
Membuat kueri menggunakan penanda logName =~ "/my%2Flog$"
Kueri tidak cocok dengan pola labels.pod_name !~ "foo"
Membuat kueri menggunakan operator boolean labels.env =~ ("^prod.*server" OR "^staging.*server")
Kueri yang dimulai dengan nilai logName =~ "^foo"
Kueri yang diakhiri dengan nilai logName =~ "foo$"

Menemukan entri log dengan cepat

Untuk menemukan entri log secara efisien, lakukan hal berikut:

  • Buat kueri menggunakan kolom yang diindeks.
  • Minimalkan jumlah entri log yang harus dicari.

Menggunakan kolom terindeks

Logging selalu mengindeks kolom LogEntry berikut:

Anda juga dapat menambahkan kolom terindeks kustom ke bucket log mana pun atau menggunakan fungsi SEARCH untuk mempercepat kueri Anda.

Mengoptimalkan kueri Anda

Percepat penelusuran Anda dengan mengurangi jumlah log, jumlah entri log, atau rentang waktu penelusuran Anda. Lebih baik lagi, Anda dapat mengurangi ketiganya.

Contoh: Menggunakan fungsi SEARCH

Daripada melakukan penelusuran global atau substring, Anda dapat menggunakan fungsi SEARCH untuk memanfaatkan indeks guna mengoptimalkan kueri Anda.

Contoh: Menggunakan nama log yang tepat

Tentukan log yang berisi entri log yang Anda inginkan. Pastikan Anda mengetahui nama log yang sebenarnya dengan memeriksa salah satu entri log Anda. Misalnya, panel hasil menunjukkan bahwa bagian Compute Engine berisi log bernama "activity". Setelah memeriksa entri log audit Aktivitas Admin dengan lebih cermat, log tersebut sebenarnya bernama "cloudaudit.googleapis.com/activity".

Perbandingan berikut salah. Tidak cocok dengan apa pun karena menggunakan nama log yang salah:

logName = "projects/my-project-id/logs/activity"   -- WRONG!

Perbandingan berikut benar. Log ini memilih entri log dari entri log audit Aktivitas Admin. Anda harus mengenkode URL nama log, seperti yang ditunjukkan:

logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

Contoh: Memilih entri log yang tepat

Jika Anda tahu bahwa entri log yang Anda inginkan berasal dari instance VM tertentu, tentukan instance tersebut. Periksa nama label yang tepat dengan memeriksa salah satu entri log yang ingin Anda telusuri. Dalam contoh berikut, instance_id adalah salah satu label yang diindeks:

resource.type = "gce_instance" AND
resource.labels.instance_id = "6731710280662790612"
logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

Contoh: Pilih jangka waktu yang tepat

Tentukan periode waktu untuk melakukan penelusuran. Cara cepat untuk menentukan stempel waktu yang berguna dalam format RFC 3339 adalah dengan menggunakan perintah date GNU/Linux:

$ date --rfc-3339=s
2023-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2023-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2023-06-27 12:40:00-04:00

Gunakan nilai stempel waktu ini dalam kueri berikut. Untuk membuat stempel waktu yang dapat diterima oleh Logging, ganti spasi antara tanggal dan waktu dengan huruf T.

Misalnya, untuk menelusuri dalam tiga jam terakhir:

timestamp >= "2023-06-27T14:40:00-04:00"

Sebagai contoh lain, untuk menelusuri antara tiga dan lima jam yang lalu:

timestamp >= "2023-06-27T12:40:00-04:00" AND
timestamp <= "2023-06-27T14:40:00-04:00"

Meminimalkan batasan disjungtif

Kueri yang hanya menggunakan batasan konjungtif, AND, dapat memanfaatkan indeks dengan lebih baik. Anda dapat menggunakan batasan disjungtif, OR, tetapi kueri ini dapat berjalan lambat dan tidak dapat menggunakan indeks.

Misalnya, SEARCH("foo") AND SEARCH("bar") menggunakan indeks dan akan lebih cepat daripada kueri seperti SEARCH("foo") OR SEARCH("bar").

Meminimalkan penelusuran global dan substring

Hindari godaan untuk mengambil jalan pintas saat mengetik kueri.

Contoh: Jangan gunakan penelusuran global

Jika Anda menelusuri entri log dengan "Hello Kitty" di payload:

  • Jangan menggunakan penelusuran global. Salah satu alasannya adalah karena semuanya merupakan penelusuran substring:

       "Hello Kitty"   -- THIS CAUSES A SLOW SEARCH!

  • Lakukan pembatasan penelusuran ke satu kolom, meskipun Anda harus mempertahankan penelusuran substring:

       textPayload:"Hello Kitty"

  • Lakukan pengujian kesetaraan jika Anda dapat:

       textPayload = "Hello Kitty"

  • Lakukan referensi kolom individual dalam payload, jika entri log Anda memiliki payload terstruktur:

       jsonPayload.my_favorite_cat = "Hello Kitty"

  • Gunakan kolom yang diindeks untuk membatasi penelusuran:

       logName = "projects/my-project_id/logs/somelog" AND
   jsonPayload.my_favorite_cat = "Hello Kitty"

  • Gunakan fungsi SEARCH dan tentukan teks lengkap yang akan dicocokkan. Fungsi SEARCH melakukan pencocokan yang tidak peka huruf besar/kecil:

      SEARCH("Hello Kitty")

    Jangan gunakan fungsi SEARCH dan tentukan teks sebagian. Misalnya, fungsi berikut tidak cocok dengan "Hello Kitty".

      SEARCH("Hello Kit")

Contoh penelusuran

Entri log yang ditampilkan adalah entri yang cocok dengan kueri. Jika menu Lompat ke waktu berisi nilai, maka tampilan akan men-scroll ke titik waktu tersebut. Berikut beberapa contoh kueri:

resource.type=k8s_cluster

Menemukan semua entri log Google Kubernetes Engine. Untuk mengetahui daftar jenis resource, lihat Daftar resource yang dimonitor.

Saat Anda mengetik, panel kueri akan menyarankan penyelesaian untuk kolom seperti resource.type.

resource.type=k8s_cluster AND logName:request_log

Menemukan entri log untuk cluster Google Kubernetes Engine dari nama log yang berisi request_log. Perhatikan beberapa hal:

  • Operator = adalah kesetaraan persis. Jenis resource harus persis "k8s_cluster" kecuali untuk huruf besar/kecil.
  • Operator : berarti "memiliki". Kolom logName harus berisi request_log, dalam huruf besar atau kecil. Nama log sebenarnya jauh lebih panjang. Penggunaan : dapat menyebabkan penelusuran yang lebih lambat.
  • Kedua perbandingan digabungkan dengan AND. Anda juga dapat menggunakan OR, tetapi AND diasumsikan jika Anda tidak menyertakan operator.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Menemukan entri log dengan salah satu dari dua jenis resource: instance VM Compute Engine atau instance VM AWS EC2. Entri log harus memiliki severity minimal ERROR, yang setara dengan memilih ERROR di menu tingkat keparahan antarmuka kueri.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

Menemukan semua entri log audit Aktivitas Admin di project [PROJECT_ID]. Semua log audit menggunakan nama log yang sama dalam project, tetapi memiliki jenis resource yang berbeda. ID log, cloudaudit.googleapis.com/activity harus dienkode URL dalam nama log. Menggunakan kesetaraan dalam perbandingan akan mempercepat penelusuran. Untuk mengetahui informasi selengkapnya, lihat Memahami log audit.

unicorn

Menemukan entri log yang berisi unicorn di kolom mana pun, dalam huruf besar atau kecil. Istilah penelusuran yang bukan bagian dari perbandingan kolom adalah kueri "semua kolom".

unicorn phoenix

Menemukan entri log yang berisi unicorn di beberapa kolom dan phoenix di beberapa kolom.

textPayload:(unicorn phoenix)

Menemukan entri log yang kolom textPayload-nya berisi unicorn dan phoenix dalam urutan apa pun—AND tersirat di antara kedua kata tersebut.

textPayload:"unicorn phoenix"

Menemukan entri log yang kolom textPayload-nya berisi string "unicorn phoenix".

NOT textPayload: "unicorn phoenix"

Menemukan entri log yang kolom textPayload-nya tidak berisi string "unicorn phoenix". Jenis kueri ini mengurangi entri log yang tidak diinginkan.

timestamp >= "2023-11-29T23:00:00Z" timestamp <= "2023-11-29T23:30:00Z"

Menemukan entri log dalam jangka waktu 30 menit.

Pemecahan masalah

Masalah sintaksis

Jika Anda mengalami masalah dengan ekspresi kueri, periksa hal berikut:

  • Kueri Anda mematuhi aturan sintaksis, dengan tanda kurung dan tanda kutip yang cocok.

  • Nama kolom entri log Anda dieja dengan benar.

  • Operasi Boolean menggunakan huruf kapital (AND, OR, NOT).

  • Pastikan Anda menggunakan NULL_VALUE untuk merepresentasikan nilai null JSON.

  • Ekspresi boolean sebagai batasan global atau sebagai sisi kanan perbandingan harus diberi tanda kurung agar lebih jelas. Misalnya, dua kueri berikut terlihat sama, tetapi tidak:

    insertId = "ABC-1" OR "ABC-2"  -- ERROR!?
insertId = ("ABC-1" OR "ABC-2")

  • Teks yang tidak dikutip tidak boleh berisi karakter khusus. Jika ragu, tambahkan tanda kutip ganda. Misalnya, pada contoh berikut, perbandingan pertama tidak valid karena operator substring yang disematkan (:). Perbandingan harus ditulis dengan tanda kutip:

    insertId = abc:def  -- ILLEGAL!
insertId = "abc:def"

  • Google Cloud CLI mengharuskan kueri berada dalam tanda petik ganda. Untuk menggunakan tanda kutip ganda untuk melakukan escape pada karakter khusus menggunakan perintah gcloud logging, bungkus seluruh kueri dengan tanda kutip tunggal:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'

  • Saat Anda memfilter kolom yang terkait dengan jenis pesan Any, kolom value akan otomatis dilalui. Oleh karena itu, jangan sertakan value dalam kueri.

    Misalnya, kolom Status dalam pesan AuditLog memiliki kolom details yang berjenis google.protobuf.Any. Untuk membuat kueri kolom details, hapus kolom value saat menentukan filter:

    • Lakukan

      protoPayload.status.details.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"

    • Jangan

      protoPayload.status.details.value.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"