Bahasa kueri logging

Dokumen ini menjelaskan, secara umum, bahasa kueri Logging yang Anda gunakan untuk mengkueri 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 untuk 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 logika AND dan OR. Dengan menggunakan kolom resource.type dalam contoh berikut, tata bahasa bahasa kueri Logging akan terlihat seperti ini:

  • Batasan sederhana: resource.type = "gae_app"

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

  • Batasan 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 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 cara kueri disusun dan cara pencocokan dilakukan. Beberapa contoh menggunakan komentar untuk memberikan teks penjelasan.

Perhatikan hal-hal berikut:

  • Panjang kueri tidak boleh lebih dari 20.000 karakter.

  • Bahasa kueri Logging tidak peka huruf besar/kecil, kecuali 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 dalam 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 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 tanda kurung tidak digunakan, kueri Anda mungkin tidak berfungsi sebagaimana mestinya.

Operator Boolean selalu harus dikapitalisasi. 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]: adalah operator perbandingan, 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]: adalah 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 dari jenis LogEntry. ID yang merupakan (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 pada 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 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 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 membuat kueri kolom buffering 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 tersebut harus diberi tanda kutip. Contoh:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

Untuk mengetahui daftar karakter khusus, lihat bagian string dalam 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 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. Penggunaan substring yang cocok akan menghasilkan kueri yang lebih lambat.

Bidang belum diisi

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

  • Jika kolom tersebut adalah bagian dari payload entri log (jsonPayload atau protoPayload), atau jika terdapat dalam label di bagian labels entri log, kolom tersebut 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 tersebut akan ditetapkan secara default. Perbandingan dilakukan seolah-olah kolom tersebut ada dan memiliki nilai defaultnya.

    Contoh: httpRequest.remoteIp, trace, operation.producer

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

    Contoh: thud, operation.thud, textPayload.thud

Untuk menguji apakah ada kolom yang hilang atau ditetapkan secara default tanpa menguji nilai tertentu di kolom tersebut, 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
    
  • Jika 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 berjenis 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 ini 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 dinilai berhasil.

Nilai dan konversi

Langkah pertama dalam mengevaluasi perbandingan adalah mengonversi nilai sisi sebelah 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 yang berisi angka desimal bertanda tangan yang diikuti dengan 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 jenis LogSeverity.

double

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

intNN

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

string

String apa pun yang berisi teks berenkode UTF-8 atau 7-bit ASCII. Tanda kutip tersemat 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 tanpa tanda kutip 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 integer dengan berbagai ukuran, seperti int32 dan uint64. Saat menulis nilai yang akan dikonversi ke jenis integer 64-bit, tuliskan nilai sebagai string, seperti "9223372036854775807".

Jenis kolom log

Berikut adalah cara menentukan jenis kolom entri log:

  • Kolom log yang ditentukan dalam jenis LogEntry, dan pada jenis komponen 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 dalam 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 menyertakannya 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 adalah 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 tersebut disimpan di kolom string.

Komentar

Komentar diawali 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 Anda 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 secara 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 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 panjang durasinya. Contoh: sebagai durasi, "1s">"999ms".
  • Timestamp: Persamaan berarti instan yang sama. Jika a dan b bernilai Timestamp, a < b berarti a lebih awal dari b.
  • bytes: Operand dibandingkan dengan 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 gunakan perbandingan leksikografis. Namun, penelusuran ekspresi reguler tidak dinormalisasi. Untuk mengetahui informasi selengkapnya tentang menelusuri 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 dari kolom sebelah kiri. Kecocokan substring pada kolom terindeks tidak memanfaatkan indeks log.

Pembatasan global

Jika perbandingan terdiri dari satu nilai, perbandingan 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 perbandingannya akan berhasil.

Kueri paling sederhana yang ditulis dalam batasan 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 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 melakukan kueri log terhadap 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 mudah dilakukan, pembatasan tersebut dapat berjalan 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")

sumber

Fungsi source mencocokkan 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 cocok dengan 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 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 bagian entri log yang memiliki nilai untuk disertakan oleh [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 hash. Jika nilai yang di-hash tidak didistribusikan secara seragam, sampel yang dihasilkan dapat menjadi tidak akurat. Dalam kasus terburuk, jika [FIELD] selalu berisi nilai yang sama, contoh yang dihasilkan akan berisi [FRACTION] dari semua entri log atau tanpa entri log.

Jika [FIELD] muncul dalam entri log, maka:

  • Hash dari nilai akan dihitung.
  • Nilai yang di-hash, yaitu angka, dibagi dengan nilai hash maksimum yang memungkinkan.
  • Jika pecahan 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 tersebut tidak akan dipilih untuk contoh, meskipun [FRACTION] adalah 1.
  • Jika tidak, entri log akan diperlakukan seolah-olah [FIELD] dalam entri log dan nilai [FIELD] adalah nilai defaultnya. Nilai default-nya ditentukan oleh jenis LogEntry. Untuk mengetahui informasi selengkapnya tentang kolom yang tidak ada dan secara default, baca bagian Kolom tidak ada dalam dokumen ini.

Untuk mengecualikan entri log dengan kolom default dari sampel, gunakan operator kolom tersedia, :*. Kueri berikut menghasilkan sampel 1 persen entri log yang secara eksplisit menyediakan 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 atau rentang IP. Kolom ini bisa berulang, dalam hal ini hanya satu kolom berulang yang harus memiliki alamat atau rentang yang ada 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 ini akan menampilkan nilai salah (false). Untuk mengetahui informasi selengkapnya tentang kolom yang tidak ada dan secara default, baca Kolom yang 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
  • 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 Anda:

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 dalam entri log yang akan ditelusuri.

Anda harus menentukan kolom query. Jika kolom ini tidak ditentukan, 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 backtick. Perilaku ini berbeda dengan BigQuery, yang mempertahankan kasus dalam token yang digabungkan dengan tanda aksen rendah. Untuk mengetahui informasi tentang aturan analyzer, lihat dokumen BigQuery Aturan text analyzer.

Ketika membuat penelusuran, pertimbangkan hal-hal berikut:

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

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

    Fungsi sebelumnya cocok dengan entri log jika satu kolom berisi token "world". Karena SEARCH melakukan pencocokan persis dan bukan substring yang cocok, fungsi sebelumnya tidak cocok dengan kolom yang nilainya adalah "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 menjadi masalah dan token tersebut 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; namun, urutan token tidak menjadi masalah.

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

    SEARCH(textPayload, "hello world")
    
  • Untuk menerapkan pencocokan yang tidak peka huruf besar/kecil tetapi sama persis pada frasa, tambahkan frasa tersebut 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 terkait tanggal dan waktu entri log untuk ditampilkan. Misalnya, jika Anda menambahkan kondisi berikut ke kueri, pratinjau akan menampilkan entri log dalam periode 30 menit yang ditunjukkan 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 mengenai 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 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 mengkueri pola yang berisi tanda kutip ganda, escape menggunakan garis miring terbalik.

Contoh membuat 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.*\""
Membuat 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"
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 dengan lebih efisien, lakukan hal berikut:

  • Membuat 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 berikutnya menjelaskan cara menggunakan kolom terindeks untuk meminimalkan jumlah entri log yang akan ditelusuri.

Optimalkan kueri Anda

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

Contoh: Gunakan 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 Anda. Misalnya, pratinjau menunjukkan bahwa ada log di bagian Compute Engine yang bernama "activity". Setelah diperiksa lebih dekat terhadap entri log audit Aktivitas Admin, log tersebut sebenarnya bernama "cloudaudit.googleapis.com/activity".

Perbandingan berikut salah. Hasil kueri tidak cocok apa pun karena menggunakan nama log yang salah:

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

Perbandingan berikut ini benar. Performance Planner memilih entri log dari entri log audit Aktivitas Admin. Anda harus mengenkode nama log ke URL, 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 diinginkan berasal dari instance VM tertentu, maka 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 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 untuk 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 lainnya, 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 teks "Hello Kitty" dalam payload:

  • Jangan menggunakan penelusuran global. Karena satu alasan, semuanya adalah penelusuran substring:

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

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

       textPayload:"Hello Kitty"
       

  • Gunakan pengujian kesetaraan jika Anda bisa:

       textPayload = "Hello Kitty"
       

  • Lakukan referensi pada 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 gunakan fungsi SEARCH dan tentukan teks parsial. Misalnya, fungsi berikut tidak cocok dengan "Hello Kitty".

      SEARCH("Hello Kit")
      

Menelusuri contoh

Entri log yang ditampilkan adalah entri yang cocok dengan kueri. Jika menu Lompat ke waktu 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 pelengkapan 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 huruf besar/kecil.
  • Operator : berarti "has". Kolom logName harus berisi request_log, dalam huruf apa pun. Nama log yang sebenarnya jauh lebih panjang. Menggunakan : dapat menyebabkan penelusuran menjadi lebih lambat.
  • Kedua perbandingan tersebut 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 seriusan 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 di kolom apa pun, dalam huruf besar apa pun. Istilah penelusuran yang bukan bagian dari perbandingan kolom adalah kueri "semua kolom".

unicorn phoenix

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

textPayload:(unicorn phoenix)

Menemukan entri log dengan kolom textPayload yang berisi unicorn dan phoenix dalam urutan apa pun—AND implisit di antara dua kata.

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 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 petik yang cocok.

  • Nama kolom entri log Anda sudah 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 (:). Perbandingannya harus ditulis dengan tanda kutip:

    insertId = abc:def  -- ILLEGAL!
    insertId = "abc:def"
    
  • Google Cloud CLI mengharuskan kueri ditulis 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.*"