Migliorare i tempi di query con l'indicizzazione personalizzata

Questo documento descrive come aggiungere campi LogEntry indicizzati ai bucket di Cloud Logging per velocizzare le query sui dati dei log.

Panoramica

Le prestazioni delle query sono fondamentali per qualsiasi soluzione di logging. Man mano che i workload vengono scalati e i volumi di log corrispondenti aumentano, l'indicizzazione dei dati dei log più utilizzati può ridurre il tempo di esecuzione delle query.

Per migliorare le prestazioni delle query, Logging indicizza automaticamente i seguenti campi LogEntry:

Oltre ai campi indicizzati automaticamente da Logging, puoi anche indirizzare un bucket di log per indicizzare altri campi LogEntry creando un indice personalizzato per il bucket.

Ad esempio, supponiamo che le espressioni di query includano spesso il campo jsonPayload.request.status. Potresti configurare un indice personalizzato per un bucket che includa jsonPayload.request.status; qualsiasi query successiva sui dati del bucket farebbe riferimento ai dati jsonPayload.request.status indicizzati se l'espressione di query include questo campo.

Utilizzando Google Cloud CLI o l'API Logging, puoi aggiungere indici personalizzati ai bucket log esistenti o nuovi. Quando selezioni altri campi da includere nell'indice personalizzato, tieni presente le seguenti limitazioni:

  • Puoi aggiungere fino a 20 campi per indice personalizzato.
  • Dopo aver configurato o aggiornato l'indice personalizzato di un bucket, devi attendere un'ora prima che le modifiche vengano applicate alle query. Questa latenza garantisce la correttezza dei risultati delle query e accetta i log scritti in passato.
  • La registrazione applica l'indicizzazione personalizzata ai dati archiviati nei bucket di log dopo la creazione o la modifica dell'indice; le modifiche agli indici personalizzati non vengono applicate ai log in modo retroattivo.

Prima di iniziare

Prima di iniziare a configurare un indice personalizzato:

Definisci l'indice personalizzato

Per ogni campo che aggiungi all'indice personalizzato di un bucket, definisci due attributi: un percorso del campo e un tipo di campo:

  • fieldPath: descrive il percorso specifico del campo LogEntry nelle voci di log. Ad esempio: jsonPayload.req_status.
  • type: indica se il campo è di tipo stringa o intero. I valori possibili sono INDEX_TYPE_STRING e INDEX_TYPE_INTEGER.

È possibile aggiungere un indice personalizzato creando un nuovo bucket o aggiornandone uno esistente. Per saperne di più sulla configurazione dei bucket, consulta Configura i bucket di log.

Per configurare un indice personalizzato durante la creazione di un bucket:

gcloud

Utilizza il comando gcloud logging buckets create e imposta il flag --index:

gcloud logging buckets create BUCKET_NAME \
--location=LOCATION \
--description="DESCRIPTION" \
--index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Comando di esempio:

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

Per creare un bucket, utilizza projects.locations.buckets.create nell'API Logging. Prepara gli argomenti per il metodo nel seguente modo:

  1. Imposta il parametro parent in modo che corrisponda alla risorsa in cui creare il bucket: projects/PROJECT_ID/locations/LOCATION

    La variabile LOCATION si riferisce alla regione in cui vuoi che vengano archiviati i log.

    Ad esempio, se vuoi creare un bucket per il progetto my-project nella regione asia-east2, il parametro parent avrà il seguente aspetto: projects/my-project/locations/asia-east2

  2. Imposta il parametro bucketId, ad esempio my-bucket.

  3. Nel corpo della richiesta LogBucket, configura l'oggetto IndexConfig per creare l'indice personalizzato.

  4. Chiama projects.locations.buckets.create per creare il bucket.

Per aggiornare un bucket esistente in modo da includere un indice personalizzato:

gcloud

Utilizza il comando gcloud logging buckets update e imposta il flag --add-index:

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--add-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Comando di esempio:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--add-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Utilizza projects.locations.buckets.patch nell'API Logging. Nel corpo della richiesta LogBucket, configura l'oggetto IndexConfig in modo da includere i campi LogEntry che vuoi indicizzare.

Eliminare un campo indicizzato personalizzato

Per eliminare un campo dall'indice personalizzato di un bucket:

gcloud

Utilizza il comando gcloud logging buckets update e imposta il flag --remove-indexes :

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--remove-indexes=INDEX_FIELD_NAME

Comando di esempio:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--remove-indexes=jsonPayload.req_status

API

Utilizza projects.locations.buckets.patch nell'API Logging. Nel corpo della richiesta LogBucket, rimuovi i campi LogEntry dall'oggetto IndexConfig.

Aggiornare il tipo di dati del campo indicizzato personalizzato

Se devi correggere il tipo di dati di un campo indicizzato personalizzato:

gcloud

Utilizza il comando gcloud logging buckets update e imposta il flag --update-index:

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--update-index=fieldPath=INDEX_FIELD_NAME,type=INDEX_TYPE

Comando di esempio:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--update-index=fieldPath=jsonPayload.req_status,type=INDEX_TYPE_INTEGER

API

Utilizza projects.locations.buckets.patch nell'API Logging. Nel corpo della richiesta LogBucket, aggiorna l'oggetto IndexConfig per fornire il tipo di dati corretto per un campo LogEntry.

Aggiorna il percorso di un campo indicizzato personalizzato

Se devi correggere il percorso del campo di un campo indicizzato personalizzato:

gcloud

Utilizza il comando gcloud logging buckets update e imposta i flag --remove-indexes e --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

Comando di esempio:

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

Utilizza projects.locations.buckets.patch nell'API Logging. Nel corpo della richiesta LogBucket, aggiorna l'oggetto IndexConfig per fornire il percorso del campo corretto per un campo LogEntry.

Elenca tutti i campi indicizzati per un bucket

Per elencare i dettagli di un bucket, inclusi i campi indicizzati personalizzati, procedi nel seguente modo:

gcloud

Utilizza il comando gcloud logging buckets describe:

gcloud logging buckets describe BUCKET_NAME \
--location=LOCATION

Comando di esempio:

gcloud logging buckets describe indexed-bucket \
--location global

API

Utilizza projects.locations.buckets.get nell'API Logging.

Cancella campi personalizzati indicizzati

Per rimuovere tutti i campi indicizzati personalizzati da un bucket:

gcloud

Utilizza il comando gcloud logging buckets update e aggiungi il flag --clear-indexes:

gcloud logging buckets update BUCKET_NAME \
--location=LOCATION \
--clear-indexes

Comando di esempio:

gcloud logging buckets update int_index_test_bucket \
--location=global \
--clear-indexes

API

Utilizza projects.locations.buckets.patch nell'API Logging. Nel corpo della richiesta LogBucket, elimina l'oggetto IndexConfig.

Eseguire query e visualizzare i dati indicizzati

Per eseguire query sui dati inclusi nei campi indicizzati personalizzati, limita l'ambito della query al bucket che contiene i campi indicizzati personalizzati e specifica la visualizzazione log appropriata:

gcloud

Per leggere i log da un bucket di log, utilizza il comando gcloud logging read e aggiungi un LOG_FILTER per includere i dati indicizzati:

gcloud logging read LOG_FILTER --bucket=BUCKET_ID --location=LOCATION --view=LOG_VIEW_ID

API

Per leggere i log da un bucket di log, utilizza il metodo entries.list. Imposta resourceNames per specificare il bucket e la visualizzazione log appropriati e imposta filter per selezionare i dati indicizzati.

Per informazioni dettagliate sulla sintassi di filtro, consulta Linguaggio di query di Logging.

Indicizzazione e tipi di campo

La configurazione dell'indicizzazione dei campi personalizzati può influire sulla modalità di archiviazione dei log nei bucket di log e sull'elaborazione delle query.

Al momento della scrittura

Registrazione dei tentativi di utilizzo dell'indice personalizzato sui dati memorizzati nei bucket dei log dopo la creazione dell'indice.

I campi indicizzati sono digitati, il che ha implicazioni per il timestamp della voce di log. Quando la voce di log viene archiviata nel bucket di log, il campo di log viene valutato in base al tipo di indice utilizzando queste regole:

  • Se il tipo di un campo è uguale a quello dell'indice, i dati vengono aggiunti all'indice letteralmente.
  • Se il tipo di campo è diverso da quello dell'indice, il logging tenta di forzarlo nel tipo dell'indice (ad esempio, da numero intero a stringa).
    • Se la conversione del tipo non riesce, i dati non vengono indicizzati. Quando la conversione del tipo va a buon fine, i dati vengono indicizzati.

Al momento della query

L'attivazione di un indice su un campo modifica il modo in cui devi eseguire query su quel campo. Per impostazione predefinita, la registrazione applica i vincoli di filtro ai campi in base al tipo di dati in ogni voce di log che viene valutata. Quando l'indicizzazione è attivata, i vincoli di filtro su un campo vengono applicati in base al tipo di indice. L'aggiunta di un indice a un campo impone uno schema a quel campo.

Quando un indice personalizzato è configurato per un bucket, i comportamenti di corrispondenza dello schema sono diversi quando vengono soddisfatte entrambe le condizioni seguenti:

  • Il tipo di dati di origine per un campo non corrisponde al tipo di indice per quel campo.
  • L'utente applica un vincolo a questo campo.

Prendi in considerazione i seguenti payload JSON:

{"jsonPayload": {"name": "A", "value": 12345}}
{"jsonPayload": {"name": "B", "value": "3"}}

Ora applica questo filtro a ciascuno:

jsonPayload.value > 20

Se il campo jsonPayoad.value non dispone di indicizzazione personalizzata, la registrazione applica la corrispondenza di tipo flessibile:

  • Per "A", la registrazione osserva che il valore della chiave "value" è in realtà un numero intero e che il vincolo "20" può essere convertito in un numero intero. La registrazione valuta quindi 12345 > 20 e restituisce "true" perché è questo il caso numericamente.

  • Per "B", Logging osserva che il valore della chiave "value" è in realtà una stringa. Poi valuta "3" > "20" e restituisce "true", poiché questo è il caso alfanumerico.

Se il campo jsonPayload.value è incluso nell'indice personalizzato, allora Logging valuta questo vincolo utilizzando l'indice anziché la logica di Logging abituale. Il comportamento cambia:

  • Se l'indice è di tipo stringa, tutti i confronti sono confronti di stringhe.
    • La voce "A" non corrisponde, poiché "12345" non è maggiore di "20" in ordine alfanumerico. La voce "B" corrisponde, poiché la stringa "3" è maggiore di "20".
  • Se l'indice è di tipo intero, tutti i confronti sono confronti tra numeri interi.
    • La voce "B" non corrisponde, poiché "3" non è maggiore di "20". numericamente. La voce "A" corrisponde, poiché "12345" è maggiore di "20".

Questa differenza di comportamento è sottile e deve essere presa in considerazione quando si definiscono e si utilizzano indici personalizzati.

Caso limite di filtro

Per l'indice di tipo intero jsonPayload.value, supponiamo che venga filtrato un valore stringa:

jsonPayload.value = "hello"

Se non è possibile forzare il valore della query al tipo di indice, l'indice viene ignorato.

Tuttavia, supponiamo che per un indice di tipo stringa passi un valore intero:

jsonPayload.value > 50

Né A né B corrispondono, in quanto né "12345" né "3" sono alfanumericamente maggiori di "50".