Dokumen ini menjelaskan cara menambahkan kolom LogEntry yang diindeks ke bucket Cloud Logging untuk mempercepat proses kueri data log Anda.
Ringkasan
Performa kueri sangat penting untuk solusi logging apa pun. Seiring peningkatan skala beban kerja dan volume log terkait meningkat, pengindeksan data log yang paling sering digunakan dapat mengurangi waktu kueri.
Untuk meningkatkan performa kueri, Logging otomatis mengindeks kolom LogEntry berikut:
- resource.type
- resource.labels.*
- logName
- keparahan
- stempel waktu
- insertId
- operation.id
- trace
- httpRequest.status
- label.*
- split.uid
Selain kolom yang diindeks oleh Logging secara otomatis, Anda juga dapat mengarahkan bucket log untuk mengindeks kolom LogEntry lainnya dengan membuat indeks kustom untuk bucket.
Misalnya, ekspresi kueri Anda sering menyertakan kolom
jsonPayload.request.status
. Anda dapat mengonfigurasi indeks kustom untuk bucket yang menyertakan jsonPayload.request.status
; kueri apa pun berikutnya pada data bucket tersebut akan mereferensikan data jsonPayload.request.status
yang diindeks jika ekspresi kueri menyertakan kolom tersebut.
Dengan Google Cloud CLI atau Logging API, Anda dapat menambahkan indeks kustom ke bucket log yang ada atau yang baru. Saat memilih kolom tambahan untuk disertakan dalam indeks kustom, perhatikan batasan berikut:
- Anda dapat menambahkan hingga 20 kolom per indeks kustom.
- Setelah mengonfigurasi atau memperbarui indeks kustom bucket, Anda harus menunggu satu jam agar perubahan diterapkan pada kueri. Latensi ini memastikan kebenaran hasil kueri dan menerima log yang ditulis sebelumnya.
- Logging menerapkan pengindeksan kustom ke data yang disimpan di bucket log setelah indeks dibuat atau diubah; perubahan pada indeks kustom tidak berlaku untuk log secara retroaktif.
Sebelum memulai
Sebelum Anda mulai mengonfigurasi indeks kustom, lakukan hal berikut:
Pastikan Anda menggunakan gcloud CLI versi terbaru. Untuk mengetahui informasi selengkapnya, lihat Mengelola komponen CLI Google Cloud.
Pastikan Anda memiliki peran Identity and Access Management dengan izin berikut:
Untuk mengetahui detail tentang peran ini, baca Kontrol akses dengan IAM.
Menentukan indeks kustom
Untuk setiap kolom yang ditambahkan ke indeks kustom bucket, Anda harus menentukan dua atribut: jalur kolom dan jenis kolom:
fieldPath
: Menjelaskan jalur spesifik ke kolom LogEntry dalam entri log Anda. Misalnya,jsonPayload.req_status
.type
: Menunjukkan apakah kolom berjenis string atau bilangan bulat. Kemungkinan nilainya adalahINDEX_TYPE_STRING
danINDEX_TYPE_INTEGER
.
Indeks kustom dapat ditambahkan dengan membuat bucket baru atau dengan mengupdate bucket yang sudah ada. Untuk informasi selengkapnya tentang cara mengonfigurasi bucket, lihat Mengonfigurasi bucket log.
Untuk mengonfigurasi indeks kustom saat membuat bucket, lakukan hal berikut:
gcloud
Gunakan
perintah gcloud logging buckets create
dan tetapkan flag --index
:
gcloud logging buckets create BUCKET_NAME\ --location=LOCATION\ --description="DESCRIPTION" \ --index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE
Contoh perintah:
gcloud logging buckets create int_index_test_bucket \ --location=global \ --description="Bucket with integer index" \ --index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER
API
Untuk membuat bucket, gunakan projects.locations.buckets.create di Logging API. Siapkan argumen ke metode sebagai berikut:
Tetapkan parameter
parent
menjadi resource untuk membuat bucket:projects/PROJECT_ID/locations/LOCATION
Variabel LOCATION mengacu pada region tempat Anda ingin menyimpan log.
Misalnya, jika Anda ingin membuat bucket untuk project
my-project
di regionasia-east2
, parameterparent
akan terlihat seperti ini:projects/my-project/locations/asia-east2
Tetapkan parameter
bucketId
; misalnya,my-bucket
.Pada isi permintaan
LogBucket
, konfigurasikan objek IndexConfig untuk membuat indeks kustom.Panggil projects.locations.buckets.create untuk membuat bucket.
Untuk mengupdate bucket yang ada agar menyertakan indeks kustom, lakukan hal berikut:
gcloud
Gunakan
perintah gcloud logging buckets update
dan tetapkan flag --add-index
:
gcloud logging buckets update BUCKET_NAME\ --location=LOCATION\ --add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE
Contoh perintah:
gcloud logging buckets update \ int_index_test_bucket \ --location=global \ --add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER
API
Gunakan projects.locations.buckets.patch di Logging API. Pada isi permintaan LogBucket, konfigurasikan objek IndexConfig untuk menyertakan kolom LogEntry yang ingin Anda indeks.
Menghapus kolom terindeks kustom
Untuk menghapus kolom dari indeks kustom bucket, lakukan langkah berikut:
gcloud
Gunakan
perintah gcloud logging buckets update
dan tetapkan flag --remove-indexes
:
gcloud logging buckets update BUCKET_NAME\ --location=LOCATION\ --remove-indexes=INDEX_FIELD_NAME
Contoh perintah:
gcloud logging buckets update int_index_test_bucket \ --location=global \ --remove-indexes=jsonPayload.req_status
API
Gunakan projects.locations.buckets.patch di Logging API. Dalam isi permintaan LogBucket, hapus kolom LogEntry dari objek IndexConfig.
Memperbarui jenis data kolom terindeks kustom
Jika Anda perlu memperbaiki jenis data kolom terindeks kustom, lakukan hal berikut:
gcloud
Gunakan
perintah gcloud logging buckets update
dan tetapkan flag --update-index
:
gcloud logging buckets update BUCKET_NAME\ --location=LOCATION\ --update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE
Contoh perintah:
gcloud logging buckets update \ int_index_test_bucket \ --location=global \ --update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER
API
Gunakan projects.locations.buckets.patch di Logging API. Dalam isi permintaan LogBucket, perbarui objek IndexConfig untuk memberikan jenis data yang benar untuk kolom LogEntry.
Memperbarui jalur kolom terindeks kustom
Jika Anda perlu memperbaiki jalur kolom untuk kolom terindeks kustom, lakukan hal berikut:
gcloud
Gunakan
perintah gcloud logging buckets update
dan tetapkan flag --remove-indexes
dan --update-index
:
gcloud logging buckets update BUCKET_NAME\ --location=LOCATION\ --remove-indexes=OLD_INDEX_FIELD_NAME \ --update-index=fieldPath=NEW_INDEX_FIELD_NAME,type=INDEX_TYPE
Contoh perintah:
gcloud logging buckets update \ int_index_test_bucket \ --location=global \ --remove-indexes=jsonPayload.req_status_old_path \ --add-index=fieldPath=jsonPayload.req_status_new_path,type=INDEX_TYPE_INTEGER
API
Gunakan projects.locations.buckets.patch di Logging API. Pada isi permintaan LogBucket, perbarui objek IndexConfig untuk memberikan jalur kolom yang benar untuk kolom LogEntry.
Mencantumkan semua kolom terindeks untuk bucket
Untuk mencantumkan detail bucket, termasuk kolom terindeks kustomnya, lakukan hal berikut:
gcloud
Guakan perintah
gcloud logging buckets describe
:
gcloud logging buckets describe BUCKET_NAME\ --location=LOCATION
Contoh perintah:
gcloud logging buckets describe indexed-bucket \ --location global
API
Gunakan projects.locations.buckets.get di Logging API.
Menghapus kolom terindeks kustom
Untuk menghapus semua kolom terindeks kustom dari bucket, lakukan langkah berikut:
gcloud
Gunakan perintah gcloud logging buckets update
dan tambahkan flag --clear-indexes
:
gcloud logging buckets update BUCKET_NAME\ --location=LOCATION\ --clear-indexes
Contoh perintah:
gcloud logging buckets update \ int_index_test_bucket \ --location=global \ --clear-indexes
API
Gunakan projects.locations.buckets.patch di Logging API. Pada isi permintaan LogBucket, hapus objek IndexConfig.
Membuat kueri dan melihat data yang diindeks
Untuk membuat kueri terhadap data yang disertakan dalam kolom terindeks kustom, batasi cakupan kueri Anda ke bucket yang berisi kolom terindeks kustom dan tentukan tampilan log yang sesuai:
gcloud
Untuk membaca log dari bucket log, gunakan perintah gcloud logging read dan tambahkan LOG_FILTER
untuk menyertakan data Anda yang diindeks:
gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=VIEW_ID
API
Untuk membaca log dari bucket log, gunakan metode entries.list
. Tetapkan resourceNames
untuk menentukan bucket dan tampilan log yang sesuai, lalu tetapkan filter
untuk memilih data yang diindeks.
Untuk informasi mendetail tentang sintaksis pemfilteran, lihat Bahasa kueri logging.
Pengindeksan dan jenis kolom
Cara Anda mengonfigurasi pengindeksan kolom kustom dapat memengaruhi cara log disimpan di bucket log dan cara kueri diproses.
Pada waktu penulisan
Logging mencoba menggunakan indeks kustom pada data yang disimpan dalam bucket log setelah indeks dibuat.
Kolom yang diindeks diketik, yang memiliki implikasi untuk stempel waktu pada entri log. Jika entri log disimpan di bucket log, kolom log akan dievaluasi terhadap jenis indeks dengan menggunakan aturan berikut:
- Jika jenis kolom sama dengan jenis indeks, data akan ditambahkan ke indeks kata demi kata.
- Jika jenis kolom berbeda dengan jenis indeks, Logging akan mencoba memaksanya ke dalam jenis indeks (misalnya, bilangan bulat ke string).
- Jika pemaksaan jenis gagal, data tidak akan diindeks. Ketika pemaksaan jenis berhasil, data akan diindeks.
Pada waktu kueri
Mengaktifkan indeks pada kolom akan mengubah cara Anda membuat kueri untuk kolom tersebut. Secara default, Logging menerapkan batasan filter ke kolom berdasarkan jenis data di setiap entri log yang dievaluasi. Saat pengindeksan diaktifkan, batasan filter pada kolom akan diterapkan berdasarkan jenis indeks. Menambahkan indeks pada kolom akan menerapkan skema pada kolom tersebut.
Jika indeks kustom dikonfigurasi untuk bucket, perilaku pencocokan skema akan berbeda saat kedua kondisi berikut terpenuhi:
- Jenis data sumber untuk suatu kolom tidak cocok dengan jenis indeks untuk kolom tersebut.
- Pengguna menerapkan batasan pada kolom tersebut.
Pertimbangkan payload JSON berikut:
{"jsonPayload": {"name": "A", "value": 12345}} {"jsonPayload": {"name": "B", "value": "3"}}
Sekarang, terapkan filter ini ke setiap:
jsonPayload.value > 20
Jika kolom jsonPayoad.value
tidak memiliki pengindeksan kustom, Logging akan menerapkan pencocokan jenis fleksibel:
Untuk "A", Logging mengamati bahwa nilai kunci "value" sebenarnya adalah bilangan bulat, dan batasan, "20", dapat dikonversi menjadi bilangan bulat. Logging kemudian mengevaluasi
12345 > 20
dan menampilkan "true" karena ini adalah kasusnya secara numerik.Untuk "B", Logging mengamati bahwa nilai kunci "value" sebenarnya adalah string. Kemudian, kode ini akan mengevaluasi
"3" > "20"
dan menampilkan "benar", karena ini merupakan kasus alfanumerik.
Jika kolom jsonPayload.value
disertakan dalam indeks kustom, Logging akan mengevaluasi batasan ini menggunakan indeks, bukan logika Logging biasa. Perilaku ini berubah:
- Jika indeks berjenis string, semua perbandingan merupakan perbandingan string.
- Entri "A" tidak cocok, karena "12345" tidak lebih besar dari "20" secara alfanumerik. Entri "B" cocok, karena string "3" lebih besar dari "20".
- Jika indeks berjenis integer, semua perbandingan merupakan perbandingan bilangan bulat.
- Entri "B" tidak cocok, karena "3" tidak lebih besar dari "20" secara numerik. Entri "A" cocok, karena "12345" lebih besar dari "20".
Perbedaan perilaku ini tidak begitu kentara dan harus dipertimbangkan saat menentukan dan menggunakan indeks kustom.
Memfilter kasus tepi
Untuk indeks jenis bilangan bulat jsonPayload.value
, misalkan nilai string
difilter:
jsonPayload.value = "hello"
Jika nilai kueri tidak dapat dikonversi ke jenis indeks, indeks akan diabaikan.
Namun, misalkan untuk indeks jenis string, Anda meneruskan nilai bilangan bulat:
jsonPayload.value > 50
A atau B tidak cocok, karena "12345" dan "3" tidak memiliki nilai alfanumerik yang lebih besar daripada "50".