Mengonfigurasi pengindeksan kustom

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:

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:
- roles/logging.admin
- roles/logging.configWriter
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 adalah INDEX_TYPE_STRING dan INDEX_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 region asia-east2, parameter parent 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".