Mengonfigurasi 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. Seiring dengan peningkatan skala beban kerja dan peningkatan volume log yang sesuai, 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 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 satu jam agar perubahan diterapkan ke 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 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 ditambahkan ke indeks kustom bucket, Anda menentukan dua atribut: jalur kolom dan jenis kolom:

  • fieldPath: Menjelaskan jalur spesifik ke kolom LogEntry dalam entri log Anda. Contohnya, jsonPayload.req_status
  • type: Menunjukkan apakah kolom tersebut 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 log disimpan.

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

Menghapus kolom kustom yang diindeks

Untuk menghapus kolom dari indeks kustom bucket, lakukan tindakan 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 kustom yang diindeks

Jika Anda perlu memperbaiki jenis data kolom yang diindeks secara 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 kustom yang diindeks

Jika Anda perlu memperbaiki jalur kolom dari kolom yang diindeks secara 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. Dalam 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

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 yang diindeks kustom dari bucket, lakukan hal 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. Dalam 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 Anda 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=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.

Pada waktu penulisan

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

Kolom yang diindeks diketik, yang memiliki implikasi pada stempel waktu di 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 menjadi jenis indeks (misalnya, bilangan bulat menjadi string).
    • Jika konversi jenis gagal, data tidak akan diindeks. Jika konversi jenis berhasil, data akan diindeks.

Pada waktu kueri

Mengaktifkan indeks pada kolom akan mengubah cara Anda membuat kueri pada kolom tersebut. Secara default, Logging menerapkan batasan filter ke kolom berdasarkan jenis data dalam 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 berikut 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:

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 bahwa batasan, "20", dapat dikonversi menjadi bilangan bulat. Logging kemudian mengevaluasi 12345 > 20 dan menampilkan "true" karena ini adalah kasus secara numerik.

  • Untuk "B", Logging mengamati bahwa nilai kunci "value" sebenarnya adalah string. Kemudian, kode ini 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. Perilaku 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.

Memfilter kasus ekstrem

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, misalnya untuk indeks jenis string, Anda meneruskan nilai bilangan bulat:

jsonPayload.value > 50

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