Bahasa kueri Logging

Dokumen ini menjelaskan, pada tingkat tinggi, bahasa kueri Logging yang Anda gunakan untuk membuat kueri dan memfilter data Cloud Logging.

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

Untuk mengetahui 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 konsol Google Cloud, Logging API, atau antarmuka command line. Anda dapat menggunakan bahasa kueri Logging untuk membuat kueri data dan menulis filter guna membuat sink dan metrik berbasis log.

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

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

  • Batasan sederhana: resource.type = "gae_app"

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

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

    • Alternatifnya: resource.type = ("gae_app" OR "gce_instance")

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

Berikut ini adalah contoh kueri yang sederhana:

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

Kueri ini cocok dengan entri log dari Compute Engine yang memiliki nilai keparahan minimal ERROR dan yang kolom textPayload-nya tidak berisi string robot 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 bagaimana kueri disusun dan bagaimana pencocokan dilakukan. Beberapa contoh menggunakan komentar untuk memberikan teks penjelas.

Perhatikan hal-hal berikut:

  • Panjang kueri tidak boleh melebihi 20.000 karakter.

  • Bahasa kueri Logging tidak peka huruf besar/kecil, kecuali untuk ekspresi reguler.

Ringkasan sintaksis

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

Kueri adalah string yang berisi ekspresi:

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

Perbandingan adalah nilai tunggal atau ekspresi Boolean:

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

Baris pertama adalah contoh perbandingan yang merupakan nilai tunggal. Jenis perbandingan ini adalah 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 perbandingannya berhasil.

Baris kedua adalah contoh perbandingan yang merupakan ekspresi Boolean dari bentuk [FIELD_NAME] [OP] [VALUE]. Elemen perbandingan dijelaskan di bawah ini:

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

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

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

Operator Boolean

Operator Boolean AND dan OR adalah operator hubungan pendek. Operator NOT memiliki prioritas tertinggi, diikuti oleh OR dan AND dalam urutan tersebut. Misalnya, dua ekspresi berikut adalah 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 adalah 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 secara bertingkat. Jika tanda kurung tidak digunakan, kueri Anda mungkin tidak berfungsi sebagaimana mestinya.

Operator Boolean selalu harus menggunakan huruf besar. Huruf kecil and, or, dan not diurai sebagai istilah penelusuran.

Perbandingan

Perbandingan memiliki bentuk berikut:

[FIELD_NAME] [OP] [VALUE]

Elemen perbandingan dijelaskan di bawah ini:

  • [FIELD_NAME]: adalah nama jalur kolom dalam entri log. Contoh nama kolom adalah:

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

    Jika komponen nama jalur memiliki karakter khusus, nama jalur harus dikutip dua kali. Misalnya, compute.googleapis.com/resource_id harus diberi tanda kutip ganda karena berisi garis miring /.

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

  • [OP]: merupakan operator perbandingan, dengan salah satu dari berikut ini:

    =           -- 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]: merupakan angka, string, fungsi, atau ekspresi tanda kurung. String digunakan untuk mewakili teks arbitrer, plus 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 yang diberi tanda kurung, nama kolom dan operator perbandingan akan 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". Yang kedua memeriksa apakah nilai kolom animal berisi kata "nice" dan "pet", dalam urutan apa pun.

ID jalur kolom

Semua entri log adalah instance jenis LogEntry. ID yang berada (atau dimulai) di 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 oleh level 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 { variabel }
  • labels { variabel }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, variabel }
  • 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, ID berikutnya harus berupa kolom dalam jenis MonitoredResource.

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

  • labels.[KEY] Jika ID jalur pertama Anda adalah labels, ID berikutnya, [KEY], harus merupakan salah satu kunci dari key-value pair 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 huruf besar dan format kuncinya dalam ekspresi.

Misalnya, jsonPayload adalah kolom struct, sehingga nama kolom yang disusun bertingkat dalam jsonPayload seperti jsonPayload.end_time berbeda dengan jsonPayload.endTime. Demikian pula, untuk kolom peta seperti labels, kunci label labels.env_name berbeda dengan labels.envName. Sebaliknya, saat membuat kueri untuk kolom buffering protokol reguler protoPayload, Anda tidak perlu mempertahankan kasus.

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

Karakter khusus

Jika kolom LogEntry berisi karakter khusus, kolom log tersebut harus dikutip. Contoh:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

Untuk daftar karakter khusus, lihat bagian string pada 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 dimonitor

Untuk kueri yang lebih cepat, tentukan jenis resource yang dipantau. Untuk 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 dipantau dalam log diindeks. Menggunakan kecocokan substring akan menghasilkan kueri yang lebih lambat.

Bidang belum diisi

Jika Anda menggunakan nama kolom dalam kueri, dan kolom tersebut tidak muncul di entri log, berarti kolom tersebut tidak ada, undefined, atau default:

  • Jika kolom merupakan bagian dari payload entri log (jsonPayload atau protoPayload), atau jika kolom tersebut berada dalam label di bagian labels entri log, kolom ini tidak ada. Penggunaan kolom yang tidak ada tidak akan menampilkan error, tetapi semua perbandingan yang menggunakan kolom yang tidak ada akan gagal secara otomatis.

    Contoh: jsonPayload.nearest_store, protoPayload.name.nickname

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

    Contoh: httpRequest.remoteIp, trace, operation.producer

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

    Contoh: thud, operation.thud, textPayload.thud

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

operation.id:*

Perhatikan perilaku kueri berikut:

  • Saat Anda menggunakan operator NOT Boolean di kolom yang tidak ada, hasilnya adalah TRUE:

    -- Returns TRUE
NOT missingField=foo

  • Saat Anda menggunakan operator perbandingan tidak sama dengan != di 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 nilai tunggal, seperti 174.4 atau -1. string juga dianggap sebagai skalar. Kolom yang dapat dikonversi menjadi (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, jsonPayload.x.age akan memiliki nilai 24.

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

    {8.5, 9, 6}

    Jika 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, keseluruhan perbandingan bernilai berhasil.

Nilai dan konversi

Langkah pertama dalam mengevaluasi perbandingan adalah dengan mengonversi nilai sisi kanan menjadi 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 buffering protokol skalar. Tabel berikut menjelaskan nilai yang dapat dikonversi ke jenis kolom log:

Jenis kolom Nilai kueri yang diizinkan
bool

"Benar" atau "salah" dalam huruf besar/kecil. Contoh: "True", "true"
bytes

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

String berisi angka desimal bertanda tangan yang diikuti oleh salah satu unit "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 dari jenis LogSeverity.
double

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

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

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

Nilai string harus dikutip dua kali untuk meng-escape karakter khusus berikut:

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

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

  • Urutan escape apa pun, misalnya \t.
Timestamp

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

Bilangan bulat yang tidak ditandatangani yang tidak melebihi ukuran jenis. Contoh: "1234".

Jika percobaan konversi gagal, perbandingan akan gagal.

Jika konversi memerlukan string, Anda juga dapat menggunakan angka atau teks yang tidak dikutip jika tidak berisi karakter khusus seperti spasi dan operator. Demikian pula, jika konversi memerlukan angka, Anda dapat menggunakan string yang kontennya berupa angka.

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

Jenis kolom log

Berikut adalah cara menentukan jenis kolom entri log:

  • Kolom log yang ditentukan dengan jenis LogEntry, dan di jenis komponennya adalah kolom buffering protokol. Kolom buffering protokol memiliki jenis eksplisit.

  • Kolom log yang merupakan bagian dari objek protoPayload juga merupakan kolom buffering protokol dan memiliki jenis eksplisit. Nama jenis buffering 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 dilewati. Oleh karena itu, jangan sertakan dalam kueri. Untuk informasi selengkapnya, lihat Pemecahan masalah.

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

    • Kolom yang nilainya berupa angka yang tidak dikutip 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 dalam kolom string, karena tidak dapat direpresentasikan secara persis sebagai nilai double.

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

Komentar

Komentar diawali dengan dua tanda hubung (--), dan teks 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 Anda dengan informasi tentang apa yang dilakukan 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

Makna operator kesetaraan (=, !=) dan ketidaksetaraan (<, <=, >, >=) bergantung pada jenis dasar nama kolom sebelah kiri.

  • Semua jenis numerik: Kesetaraan dan ketidaksetaraan memiliki arti normal untuk angka.
  • bool: Persamaan berarti nilai Boolean yang sama. Ketidaksetaraan ditentukan oleh true>false.
  • enum: Persamaan berarti nilai enumerasi yang sama. Ketidaksetaraan menggunakan nilai numerik yang mendasarinya dari literal enumerasi.
  • Duration: Persamaan berarti durasi durasi yang sama. Ketidaksetaraan didasarkan pada durasi durasi. Contoh: sebagai durasi, "1s">"999ms".
  • Timestamp: Kesetaraan berarti waktu yang sama. Jika a dan b adalah nilai Timestamp, a < b berarti a lebih awal dari b.
  • bytes: Operand dibandingkan setiap byte-nya, 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 lebih lanjut mengenai penelusuran entri log menggunakan ekspresi reguler, lihat Menggunakan ekspresi reguler.

Operator substring (:) berlaku untuk string dan bytes, dan ditangani seperti kesetaraan kecuali bahwa operand kanan hanya perlu sama dengan beberapa bagian kolom sebelah kiri. Kecocokan substring pada kolom terindeks tidak memanfaatkan indeks log.

Pembatasan global

Jika perbandingan terdiri dari satu nilai, hal ini disebut pembatasan global. Logging menggunakan operator has (:) untuk menentukan apakah ada kolom dalam entri log, atau apakah payload-nya, berisi batasan global. Jika ya, maka 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 kasus ini, ada tiga pembatasan global: cat, hat, dan bat. Pembatasan global ini diterapkan secara terpisah dan hasilnya digabungkan, seolah-olah ekspresi telah ditulis tanpa tanda kurung.

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

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

Meskipun pembatasan global itu mudah, pembatasan tersebut bisa berlangsung lambat. 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 yang diberi tanda kurung. Fungsi-fungsi tersebut dijelaskan di bagian berikut.

log_id

Fungsi log_id menampilkan entri log yang cocok dengan argumen [LOG_ID] yang diberikan dari kolom logName:

log_id([LOG_ID])

Misalnya, kueri berikut menampilkan semua entri log dengan cloudaudit.googleapis.com%2Factivity [LOG_ID]:

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

melakukan transmisi

Fungsi cast menerima dua parameter; kolom LogEntry yang akan ditransmisikan dan jenis data yang digunakan untuk mengonversi 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 mentransmisikan kolom timestamp menjadi STRING dan menentukan zona waktu America/New_York:

cast(timestamp, STRING, TIMEZONE("America/New_York")) =~ "^2023-01-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-penangkap (?:...) harus digunakan jika pengelompokan tambahan diperlukan untuk ekspresi reguler. Beberapa grup tangkapan atau tidak ada grup tangkapan akan menghasilkan error.

Anda dapat membuat rantai fungsi cast dan regexp_extract:

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

Contoh sebelumnya mentransmisikan kolom timestamp sebagai string. Ekspresi reguler menangkap bagian milidetik dari string timestamp dan mentransmisikannya ke bilangan bulat untuk melakukan perbandingan numerik. Semua entri log yang berisi stempel waktu dengan kolom milidetik yang kurang dari 500 akan ditampilkan.

sumber

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

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

Untuk membuat kueri log pada level resource tertentu, gunakan sintaksis berikut:

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

contoh

Fungsi sample memilih sebagian dari jumlah total entri log:

sample([FIELD], [FRACTION])

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

[FRACTION] adalah pecahan entri log yang memiliki nilai untuk disertakan [FIELD]. Ini adalah angka yang lebih besar dari 0,0 dan tidak lebih besar dari 1,0. Misalnya, jika Anda menentukan 0.01, sampel akan 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 didistribusikan secara seragam, sampel yang dihasilkan dapat mengalami bias. 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, yaitu angka, dibagi dengan nilai hash maksimum yang memungkinkan.
  • Jika fraksi yang dihasilkan kurang dari atau sama dengan [FRACTION], entri log akan disertakan dalam sampel; jika tidak, entri log akan 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 akan dipilih untuk contoh, meskipun [FRACTION] adalah 1.
  • Jika tidak, entri log akan diperlakukan seolah-olah [FIELD] berada dalam entri log dan nilai [FIELD] adalah nilai default-nya. Nilai default ditentukan oleh jenis LogEntry. Untuk mengetahui informasi selengkapnya tentang kolom yang tidak ada dan ditetapkan secara default, lihat Kolom yang tidak ada dalam dokumen ini.

Untuk mengecualikan entri log dengan kolom default dari contoh, gunakan operator kolom tersedia, :*. Kueri berikut menghasilkan 1 persen sampel entri log yang 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 ada dalam subnet. Anda dapat menggunakannya 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 atau rentang IP. Kolom ini dapat berulang, dalam hal ini hanya satu dari kolom berulang yang harus memiliki alamat atau rentang yang terdapat dalam subnet.

[SUBNET] adalah konstanta string untuk alamat atau rentang IP. Akan terjadi error jika [SUBNET] bukan alamat atau rentang IP resmi, seperti yang akan 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 false. Untuk mengetahui informasi selengkapnya tentang kolom yang tidak ada dan ditetapkan secara default, lihat Kolom tidak ada dalam dokumen ini.

Contoh alamat dan rentang IP yang didukung adalah sebagai berikut:

  • IPv4: 10.1.2.3
  • Subnet IPv4: 10.1.2.0/24
  • IPv6 CIDR: 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 ditelusuri. Di formulir kedua, Anda menentukan kolom di entri log yang akan ditelusuri.

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

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

Saat melakukan penelusuran, pertimbangkan hal-hal berikut:

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

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

    Fungsi sebelumnya akan cocok dengan entri log jika satu kolom berisi token "world". Karena SEARCH melakukan pencocokan persis dan bukan pencocokan substring, fungsi sebelumnya tidak cocok dengan kolom yang nilainya "seluruh dunia".

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

    Fungsi berikut memberikan 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. Pencocokan terjadi jika kolom tersebut berisi semua token; tetapi urutan token tidak berpengaruh.

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

    SEARCH(textPayload, "hello world")

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

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

    Karena {i>backtick<i} digunakan dalam fungsi berikut, hasil yang diperoleh berbeda:

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

Bahasa kueri Logging mendukung berbagai cara untuk menelusuri data log Anda. Saat menelusuri string, akan 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 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 ditampilkan. Misalnya, jika Anda menambahkan kondisi berikut ke kueri, pratinjau akan menampilkan entri log dalam periode 30 menit yang ditunjukkan dengan tepat dan Anda tidak akan dapat men-scroll di luar rentang tanggal tersebut:

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

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

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 > "2016-11-29"

Menggunakan ekspresi reguler

Anda dapat menggunakan ekspresi reguler untuk membuat kueri dan membuat filter untuk sink, metrik, dan di mana pun filter log digunakan. Anda dapat menggunakan ekspresi reguler di Builder kueri dan dengan Google Cloud CLI.

Ekspresi reguler adalah urutan karakter yang mendefinisikan 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 bidang berjenis string yang dapat dicocokkan dengan ekspresi reguler.

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

  • Kueri peka huruf besar/kecil dan tidak ditautkan 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 Anda coba cocokkan harus berada dalam tanda kutip ganda. Untuk membuat kueri pola yang berisi tanda kutip ganda, ganti dengan 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 kutip jsonPayload.message =~ "field1=\"bar.*\""
Kueri menggunakan boolean or labels.pod_name =~ "(foo|bar)"
Membuat kueri menggunakan anchor logName =~ "/my%2Flog$"
Kueri tidak cocok dengan pola labels.pod_name !~ "foo"
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 dengan lebih efisien, lakukan hal berikut:

  • Kueri menggunakan kolom terindeks.
  • Minimalkan jumlah entri log yang harus ditelusuri.

Menggunakan kolom terindeks

Logging selalu mengindeks kolom LogEntry berikut:

Anda juga dapat menambahkan kolom terindeks kustom ke bucket log mana pun.

Bagian selanjutnya menjelaskan cara menggunakan kolom terindeks untuk meminimalkan jumlah entri log yang akan ditelusuri.

Optimalkan 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: Gunakan nama log yang benar

Tentukan log yang berisi entri log yang Anda minati. Pastikan Anda mengetahui nama log yang sebenarnya dengan memeriksa salah satu entri log Anda. Misalnya, pratinjau menunjukkan bahwa ada log di bagian Compute Engine yang bernama "activity". Setelah pemeriksaan entri log audit Aktivitas Admin lebih dekat, log tersebut sebenarnya diberi nama "cloudaudit.googleapis.com/activity".

Perbandingan berikut salah. Kode ini tidak cocok dengan apa pun karena menggunakan nama log yang salah:

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

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

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

Contoh: Memilih entri log yang tepat

Jika Anda mengetahui bahwa entri log yang diinginkan 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 jangka waktu penelusuran. Cara cepat untuk menentukan stempel waktu yang berguna dalam format RFC 3339 adalah dengan menggunakan perintah date GNU/Linux:

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-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 melakukan penelusuran dalam tiga jam terakhir:

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

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

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

Meminimalkan penelusuran global dan substring

Hindari keinginan untuk mengambil pintasan saat mengetik kueri.

Contoh: Jangan gunakan penelusuran global

Jika Anda menelusuri entri log dengan tulisan "Hello Kitty" dalam payload:

  • Jangan gunakan penelusuran global. Karena satu alasan, semuanya merupakan penelusuran substring:

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

  • Lakukan batasi penelusuran ke satu kolom, meskipun Anda harus tetap menggunakan penelusuran substring:

       textPayload:"Hello Kitty"

  • Gunakan pengujian kesetaraan jika Anda dapat:

       textPayload = "Hello Kitty"

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

       jsonPayload.my_favorite_cat = "Hello Kitty"

  • Gunakan kolom terindeks untuk membatasi penelusuran:

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

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

      SEARCH("Hello Kitty")

    Jangan menggunakan fungsi SEARCH dan menentukan teks parsial. Misalnya, fungsi berikut tidak cocok dengan "Hello Kitty".

      SEARCH("Hello Kit")

Menelusuri contoh

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

resource.type=gae_app

Menemukan semua entri log App Engine. Untuk daftar jenis resource, lihat Daftar resource yang dimonitor.

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

resource.type=gae_app AND logName:request_log

Menemukan entri log untuk aplikasi App Engine dari nama log yang berisi request_log. Perhatikan beberapa hal:

  • Operator = adalah kesetaraan persis. Jenis resource harus persis "gae_app" kecuali untuk kapitalisasi huruf.
  • Operator : berarti "has". Kolom logName harus berisi request_log, dalam huruf apa pun. Nama log sebenarnya jauh lebih panjang. Penggunaan : dapat menyebabkan penelusuran yang lebih lambat.
  • Kedua perbandingan tersebut digabungkan dengan AND. Anda juga dapat menggunakan OR, tetapi AND akan 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 setidaknya 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 dalam project [PROJECT_ID]. Semua log audit menggunakan nama log yang sama dalam sebuah project, tetapi memiliki jenis resource yang berbeda. ID log, cloudaudit.googleapis.com/activity harus dienkode ke URL dalam nama log. Menggunakan kesetaraan dalam perbandingan akan mempercepat penelusuran. Untuk informasi selengkapnya, lihat Memahami log audit.

unicorn

Menemukan entri log yang berisi unicorn dalam kolom apa pun, dalam huruf besar/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 dengan kolom textPayload yang berisi unicorn dan phoenix dalam urutan apa pun—AND bersifat implisit 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 >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

Menemukan entri log dalam periode 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 petik yang cocok.

  • Nama kolom entri log Anda dieja dengan benar.

  • Operasi Boolean menggunakan huruf besar (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 di bawah ini 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, perbandingan pertama di bawah ini ilegal karena operator substring yang disematkan (:). Perbandingan harus ditulis dengan tanda kutip:

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

  • Google Cloud CLI mengharuskan kueri ditulis dalam tanda kutip ganda. Agar dapat menggunakan tanda kutip ganda untuk menghindari karakter khusus menggunakan perintah gcloud logging, gabungkan 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 dilewati. 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:

    • Anjuran

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

    • Larangan

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