Migliorare i tempi di query con l'indicizzazione personalizzata

Gli indici personalizzati in Cloud Logging consentono di indicizzare i campi LogEntry sottoposti di frequente a query nei bucket di log per velocizzare le query sui dati di log ad alto volume. Oltre ai campi che Logging indicizza automaticamente, puoi configurare indici personalizzati su campi di tipo stringa o numero intero per bucket nuovi o esistenti.

Panoramica

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

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

Oltre ai campi che Logging indicizza automaticamente, 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. Puoi configurare un indice personalizzato per un bucket che includa jsonPayload.request.status; qualsiasi query successiva sui dati di quel bucket farà riferimento ai dati jsonPayload.request.status indicizzati se l'espressione di query include quel campo.

Utilizzando Google Cloud CLI o l'API Logging, puoi aggiungere indici personalizzati ai bucket di log esistenti o nuovi. Quando selezioni campi aggiuntivi 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.
  • Logging 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 si applicano ai log retroattivamente.

Prima di iniziare

Prima di iniziare a configurare un indice personalizzato, segui questi passaggi:

Definisci l'indice personalizzato

Per ogni campo aggiunto 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 numero intero. I valori possibili sono INDEX_TYPE_STRING e INDEX_TYPE_INTEGER.

Un indice personalizzato può essere aggiunto creando un nuovo bucket o aggiornando un bucket 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, segui questi passaggi:

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 come segue:

  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 archiviare i log.

    Ad esempio, se vuoi creare un bucket per il progetto my-project nella regione asia-east2, il parametro parent sarà simile al seguente: 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, segui questi passaggi:

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.

Elimina un campo indicizzato personalizzato

Per eliminare un campo dall'indice personalizzato di un bucket, segui questi passaggi:

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.

Aggiorna il tipo di dati del campo indicizzato personalizzato

Se devi correggere il tipo di dati di un campo indicizzato personalizzato, segui questi passaggi:

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 di un campo indicizzato personalizzato, segui questi passaggi:

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, segui questi passaggi:

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 i campi indicizzati personalizzati

Per rimuovere tutti i campi indicizzati personalizzati da un bucket, segui questi passaggi:

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.

Esegui query e visualizza 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 campi

La configurazione dell'indicizzazione dei campi personalizzati può influire sul modo in cui i log vengono archiviati nei bucket di log e sul modo in cui vengono elaborate le query.

Al momento della scrittura

Logging tenta di utilizzare l'indice personalizzato sui dati archiviati nei bucket di log dopo la creazione dell'indice.

I campi indicizzati sono digitati, il che ha implicazioni sul 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 è lo stesso del tipo di indice, i dati vengono aggiunti all'indice alla lettera.
  • Se il tipo di campo è diverso da quello dell'indice, Logging tenta di forzarlo nel tipo di indice (ad esempio, da numero intero a stringa).
    • Se la coercizione del tipo non va a buon fine, i dati non vengono indicizzati. Se la coercizione del tipo va a buon fine, i dati vengono indicizzati.

Al momento della query

L'abilitazione di un indice su un campo modifica il modo in cui devi eseguire query su quel campo. Per impostazione predefinita, Logging applica i vincoli di filtro ai campi in base al tipo di dati in ogni voce di log in fase di valutazione. Quando l'indicizzazione è abilitata, 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 differiscono quando vengono soddisfatte entrambe le seguenti condizioni:

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

Considera 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 jsonPayload.value non dispone di indicizzazione personalizzata, Logging applica la corrispondenza di tipo flessibile:

  • Per "A", Logging osserva che il valore della chiave "value" è in realtà un numero intero e che il vincolo "20" può essere convertito in un numero intero. Logging 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, Logging valuta questo vincolo utilizzando l'indice anziché la consueta logica di Logging. 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 termini alfanumerici. La voce "B" corrisponde, poiché la stringa "3" è maggiore di "20".
  • Se l'indice è di tipo intero, tutti i confronti sono confronti di 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 è minima 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 il valore della query non può essere convertito nel tipo di indice, l'indice viene ignorato.

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

jsonPayload.value > 50

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