Meningkatkan waktu kueri dengan pengindeksan kustom

Dokumen ini menjelaskan cara menambahkan kolom LogEntry yang diindeks ke bucket Cloud Logging untuk mempercepat kueri data log Anda.

Ringkasan

Performa kueri sangat penting untuk solusi logging apa pun. Saat beban kerja meningkat dan volume log yang sesuai meningkat, pengindeksan data log yang paling sering digunakan dapat mengurangi waktu kueri.

Untuk meningkatkan performa kueri, Logging otomatis mengindeks berikut LogEntry kolom:

Selain kolom yang diindeks secara otomatis oleh Logging, Anda juga dapat mengarahkan bucket log untuk mengindeks kolom LogEntry lainnya dengan membuat indeks kustom untuk bucket tersebut.

Misalnya, anggaplah ekspresi kueri Anda sering menyertakan kolom jsonPayload.request.status. Anda dapat mengonfigurasi indeks kustom untuk bucket yang menyertakan jsonPayload.request.status; kueri berikutnya pada data bucket tersebut akan mereferensikan data jsonPayload.request.status yang diindeks jika ekspresi kueri menyertakan kolom tersebut.

Dengan menggunakan Google Cloud CLI atau Logging API, Anda dapat menambahkan indeks kustom ke bucket log yang ada atau baru. Saat Anda 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 selama satu jam agar perubahan diterapkan ke kueri Anda. Latensi ini memastikan kebenaran hasil kueri dan menerima log yang ditulis pada masa lalu.
  • 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 retrospektif.

Sebelum memulai

Sebelum mulai mengonfigurasi indeks kustom, lakukan hal berikut:

  • Pastikan Anda menggunakan gcloud CLI versi terbaru . Untuk mengetahui informasi selengkapnya, lihat Mengelola komponen Google Cloud CLI.

  • Pastikan Anda memiliki peran Identity and Access Management dengan izin berikut:

    Untuk mengetahui detail tentang peran ini, lihat Kontrol akses dengan IAM.

Menentukan indeks kustom

Untuk setiap kolom yang Anda tambahkan ke indeks kustom bucket, Anda menentukan dua atribut: jalur kolom dan jenis kolom:

  • fieldPath: Menjelaskan jalur spesifik ke LogEntry kolom dalam entri log Anda. Misalnya, jsonPayload.req_status.
  • type: Menunjukkan apakah kolom berjenis string atau bilangan bulat. Nilai yang mungkin adalah INDEX_TYPE_STRING dan INDEX_TYPE_INTEGER.

Indeks kustom dapat ditambahkan dengan membuat bucket baru atau dengan memperbarui bucket yang ada. Untuk mengetahui 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:

  1. Tetapkan parameter parent sebagai resource tempat 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 Anda akan terlihat seperti ini: projects/my-project/locations/asia-east2

  2. Tetapkan parameter bucketId; misalnya, my-bucket.

  3. Di isi permintaan LogBucket, konfigurasikan objek IndexConfig untuk membuat indeks kustom.

  4. Panggil projects.locations.buckets.create untuk membuat bucket.

Untuk memperbarui 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. Di isi permintaan LogBucket, konfigurasikan objek IndexConfig untuk menyertakan kolom LogEntry yang ingin Anda indeks.

Menghapus kolom yang diindeks kustom

Untuk menghapus kolom dari indeks kustom bucket, lakukan hal 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. Di isi permintaan LogBucket, hapus LogEntry dari objek IndexConfig.

Memperbarui jenis data kolom yang diindeks kustom

Jika Anda perlu memperbaiki jenis data kolom yang diindeks 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. Di isi permintaan LogBucket, perbarui objek IndexConfig untuk memberikan jenis data yang benar untuk kolom LogEntry.

Memperbarui jalur kolom yang diindeks kustom

Jika Anda perlu memperbaiki jalur kolom yang diindeks 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. Di isi permintaan LogBucket, perbarui objek IndexConfig untuk memberikan jalur kolom yang benar untuk kolom LogEntry.

Mencantumkan semua kolom yang diindeks untuk bucket

Untuk mencantumkan detail bucket, termasuk kolom yang diindeks kustom, lakukan hal berikut:

gcloud

Gunakan 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 yang diindeks kustom

Untuk menghapus semua kolom yang diindeks kustom dari bucket, lakukan hal berikut:

gcloud

Gunakan gcloud logging buckets update perintah 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. Di isi permintaan LogBucket, hapus objek IndexConfig.

Membuat kueri dan melihat data yang diindeks

Untuk membuat kueri data yang disertakan dalam kolom yang diindeks kustom, batasi cakupan kueri ke bucket yang berisi kolom yang diindeks 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 yang diindeks:

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=LOG_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 mengetahui 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.

Saat waktu tulis

Logging mencoba menggunakan indeks kustom pada data yang disimpan di bucket log setelah indeks dibuat.

Kolom yang diindeks diketik, yang memiliki implikasi untuk stempel waktu pada entri log. Saat entri log disimpan di bucket log, kolom log dievaluasi terhadap jenis indeks menggunakan aturan berikut:

  • Jika jenis kolom sama dengan jenis indeks, data akan ditambahkan ke indeks secara verbatim.
  • Jika jenis kolom berbeda dengan jenis indeks, Logging akan mencoba memaksanya ke dalam jenis indeks (misalnya, bilangan bulat ke string).
    • Jika paksaan jenis gagal, data tidak akan diindeks. Jika paksaan jenis berhasil, data akan diindeks.

Saat waktu kueri

Mengaktifkan indeks pada kolom akan mengubah cara Anda harus membuat kueri kolom tersebut. Secara default, Logging menerapkan batasan filter ke kolom berdasarkan jenis data di setiap entri log yang sedang dievaluasi. Saat pengindeksan diaktifkan, batasan filter pada kolom diterapkan berdasarkan jenis indeks. Menambahkan indeks pada kolom akan menerapkan skema pada kolom tersebut.

Saat indeks kustom dikonfigurasi untuk bucket, perilaku pencocokan skema akan berbeda jika kedua kondisi ini terpenuhi:

  • Jenis data sumber untuk 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 payload:

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 kasus numerik.

  • Untuk "B", Logging mengamati bahwa nilai kunci "value" sebenarnya adalah string. Kemudian, Logging mengevaluasi "3" > "20" dan menampilkan "true", karena ini adalah kasus alfanumerik.

Jika kolom jsonPayload.value disertakan dalam indeks kustom, Logging akan mengevaluasi batasan ini menggunakan indeks, bukan logika Logging biasa. Perilakunya berubah:

  • Jika indeks berjenis string, semua perbandingan adalah 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 bilangan bulat, semua perbandingan adalah 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 jelas dan harus dipertimbangkan saat menentukan dan menggunakan indeks kustom.

Kasus ekstrem pemfilteran

Untuk indeks jenis bilangan bulat jsonPayload.value, anggaplah nilai string difilter:

jsonPayload.value = "hello"

Jika nilai kueri tidak dapat dipaksa ke jenis indeks, indeks akan diabaikan.

Namun, anggaplah untuk indeks jenis string, Anda meneruskan nilai bilangan bulat:

jsonPayload.value > 50

Baik A maupun B tidak cocok, karena "12345" maupun "3" tidak lebih besar dari "50" secara alfanumerik.