Bahasa kueri Logging

Dokumen ini menjelaskan, secara umum, 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 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 untuk membuat sink dan metrik berbasis log.

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

Anda dapat membuat kueri berdasarkan LogEntry kolom yang diindeks menggunakan operator logis AND dan OR. Dengan menggunakan kolom resource.type dalam contoh berikut, sintaksis 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 keparahan setidaknya 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 kueri disusun 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.

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 adalah satu nilai atau ekspresi Boolean:

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

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

Baris kedua adalah contoh perbandingan yang merupakan ekspresi Boolean dalam 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 dengan 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 menggunakan huruf besar. and, or, dan not dalam 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 ID ini:

    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 yang 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 mewakili teks arbitrer, serta 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 perbandingan Boolean dalam 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 dari 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 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 { 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, 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 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 disusun bertingkat di 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 mengkueri kolom buffering protokol reguler protoPayload, Anda tidak perlu mempertahankan kasus.

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

Karakter khusus

Jika kolom LogEntry berisi karakter khusus, kolom log harus diapit tanda kutip. Contoh:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

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

Untuk 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 dimonitor. 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 dimonitor dalam log diindeks. Menggunakan pencocokan 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, kolom tersebut tidak ada, tidak ditentukan, atau default:

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

    Contoh: jsonPayload.nearest_store, protoPayload.name.nickname

  • Jika kolom ditentukan dalam jenis LogEntry, 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 ditetapkan secara default ada tanpa menguji nilai tertentu di kolom, gunakan perbandingan :*. Misalnya, perbandingan berikut berhasil jika kolom operation.id secara eksplisit ada dalam entri log:

operation.id:*

Perhatikan perilaku kueri berikut:

  • Jika Anda menggunakan operator NOT Boolean 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, jsonPayload.x.age akan memiliki nilai 24.

  • Kolom array menyimpan daftar nilai—semuanya berjenis 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}, perbandingan:

    jsonPayload.shoeSize < 7

    setara dengan:

    8.5 < 7 OR 9 < 7 OR 6 < 7

    Dalam contoh ini, perbandingan keseluruhan dievaluasi sebagai berhasil.

Nilai dan konversi

Langkah pertama dalam mengevaluasi perbandingan adalah mengonversi nilai sebelah 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 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 atau kecil. Contoh: "Benar", "true"
bytes

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

String yang berisi angka desimal bertanda diikuti dengan salah satu unit "ns", "us", "ms", "s", "m", atau "h". Durasi akurat hingga nanodetik. Contoh: "3,2 dtk".
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" (huruf besar atau tidak). Contoh: "-3,2e-8", "nan".
intNN

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

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

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

  • String yang diawali 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 direpresentasikan dengan akurasi nanodetik.
uintNN

Semua bilangan bulat tanpa tanda tangan yang tidak melebihi ukuran jenis. Contoh: "1234".

Jika upaya konversi gagal, perbandingan juga akan gagal.

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

Jenis intNN dan uintNN mewakili jenis bilangan bulat dalam 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 adalah cara menentukan jenis kolom entri log:

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

  • Kolom log yang merupakan bagian dari objek protoPayload juga merupakan kolom buffer protokol dan memiliki jenis eksplisit. Nama jenis buffering protokol disimpan di kolom "@type" dari protoPayload. Untuk 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 berupa angka tanpa tanda kutip 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 persis seperti nilai double.

  • Jenis Duration dan Timestamp hanya dikenali di kolom buffering protokol. Di tempat lain, nilai tersebut disimpan di 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 dasar nama kolom sebelah kiri.

  • Semua jenis numerik: Persamaan dan ketidaksetaraan memiliki makna 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 yang mendasari literal enumerasi.
  • Duration: Persamaan berarti panjang durasi yang sama. Ketidaksetaraan didasarkan pada panjang durasi. Contoh: sebagai durasi, "1s">"999ms".
  • Timestamp: Persamaan berarti waktu yang sama. Jika a dan b adalah nilai Timestamp, a < b berarti a lebih awal waktunya daripada b.
  • bytes: Operand 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 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 bahwa operand sebelah kanan hanya perlu sama dengan beberapa bagian kolom sebelah kiri. Kecocokan substring pada kolom yang diindeks tidak memanfaatkan indeks log.

Pembatasan global

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

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

"The Cat in The Hat"

Anda dapat menggabungkan batasan 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, seperti ekspresi yang telah 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 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"

Sebagai ganti menggunakan batasan global, yang dapat lambat, sebaiknya Anda menggunakan fungsi SEARCH bawaan dan kueri kolom yang diindeks. Untuk 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 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")

transmisikan

Fungsi cast menerima dua parameter; kolom LogEntry yang akan ditransmisikan, dan jenis data tempat kolom dikonversi menjadi:

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 ke 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-tangkapan (?:...) harus digunakan jika pengelompokan tambahan diperlukan untuk ekspresi reguler. Beberapa grup tangkapan atau tidak ada grup tangkapan akan menyebabkan 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 kurang dari 500 akan ditampilkan.

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, penggunaan source(folders/folder_123) akan mencocokkan log dari resource folder_123, 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)
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 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 dimasukkan ke dalam [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 contoh yang dihasilkan bergantung pada distribusi nilai yang di-hash. Jika nilai hash tidak didistribusikan secara merata, sampel yang dihasilkan dapat terdistorsi. Dalam kasus terburuk, jika [FIELD] selalu berisi nilai yang sama, contoh yang dihasilkan akan berisi [FRACTION] dari semua entri log atau tidak ada entri log.

Jika [FIELD] muncul dalam entri log, berarti:

  • Hash nilai dihitung.
  • Nilai hash, yang merupakan angka, dibagi dengan nilai hash maksimum yang mungkin.
  • 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 dipilih untuk sampel, meskipun [FRACTION] adalah 1.
  • Jika tidak, entri log akan diperlakukan seolah-olah [FIELD] ada dalam entri log dan nilai [FIELD] adalah nilai default. 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 sampel, gunakan operator kolom ada, :*. Kueri berikut menghasilkan sampel 1 persen 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 terdapat 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 IP atau rentang. Kolom 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. Error akan terjadi 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 ditetapkan secara default, lihat Kolom yang tidak ada dalam dokumen ini.

Berikut adalah 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 bentuk pertama, seluruh entri log akan ditelusuri. Dalam formulir kedua, Anda menentukan kolom di 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 digabungkan dengan tanda petik terbalik. Perilaku ini berbeda dengan BigQuery, yang mempertahankan huruf besar/kecil dalam token yang diapit dengan tanda petik terbalik. Untuk 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, bukan pencocokan substring, fungsi sebelumnya tidak cocok dengan kolom yang nilainya "worldwide".

  • 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 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 jika kolom tersebut berisi semua token; tetapi, urutan token tidak penting.

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

    SEARCH(textPayload, "hello world")

  • Untuk menerapkan pencocokan persis tetapi tidak peka huruf besar/kecil pada frasa, masukkan 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 menghasilkan hasil yang berbeda:

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

Bahasa kueri Logging mendukung berbagai cara untuk menelusuri data log. Saat menelusuri string, lebih efisien untuk 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 secara 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 ditampilkan 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 sink, metrik, dan tempat 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 berjenis string yang dapat dicocokkan dengan ekspresi reguler.

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

  • Kueri peka huruf besar/kecil dan tidak diancarkan 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 petik ganda, escape pola tersebut menggunakan backslash.

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 or boolean labels.pod_name =~ "(foo|bar)"
Membuat kueri menggunakan anchor 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 diawali 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 ditelusuri.

Menggunakan kolom terindeks

Logging selalu mengindeks kolom LogEntry berikut:

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

Bagian berikutnya menjelaskan cara menggunakan kolom yang diindeks untuk meminimalkan jumlah entri log yang akan ditelusuri.

Mengoptimalkan kueri Anda

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

Contoh: Menggunakan nama log yang tepat

Tentukan log yang berisi entri log yang Anda minati. Pastikan Anda mengetahui nama log yang sebenarnya dengan memeriksa salah satu entri log. Misalnya, panel hasil menunjukkan bahwa bagian Compute Engine berisi log bernama "activity". Jika diperiksa lebih cermat, entri log audit Aktivitas Admin 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. Alat 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 entri 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: Memilih jangka waktu yang tepat

Tentukan jangka waktu untuk menelusuri. 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 di 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 penelusuran global dan substring

Hindari godaan untuk menggunakan pintasan saat mengetik kueri.

Contoh: Jangan gunakan penelusuran global

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

  • Jangan gunakan penelusuran global. Untuk satu alasan, semuanya adalah penelusuran substring:

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

  • Jangan batasi penelusuran ke satu kolom, meskipun Anda harus mempertahankan penelusuran substring:

       textPayload:"Hello Kitty"

  • Gunakan 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"

  • Lakukan penggunaan 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, tampilan akan di-scroll ke titik waktu tersebut. Berikut adalah beberapa contoh kueri:

resource.type=k8s_cluster

Menemukan semua entri log Google Kubernetes Engine. Untuk 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 berikut:

  • Operator = adalah kesetaraan persis. Jenis resource harus "k8s_cluster" persis, 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 oleh 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 setidaknya ERROR, yang setara dengan memilih ERROR di menu 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 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 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 >= "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 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 diapit tanda kurung untuk kejelasan. Misalnya, dua kueri berikut terlihat sama, tetapi tidak:

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

  • Teks tanpa tanda kutip tidak boleh berisi karakter khusus apa pun. Jika ragu, tambahkan tanda kutip ganda. Misalnya, dalam contoh berikut, perbandingan pertama tidak sah karena operator substring tersemat (:). Perbandingan harus ditulis dengan tanda kutip:

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

  • Google Cloud CLI mengharuskan kueri dalam tanda kutip ganda. Untuk menggunakan tanda kutip ganda guna meng-escape 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 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:

    • Anjuran

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

    • Larangan

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