Configurare l'indicizzazione personalizzata

Questo documento descrive come aggiungere campi LogEntry indicizzati ai bucket di Cloud Logging per eseguire più velocemente query sui dati dei log.

Panoramica

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

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

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

Ad esempio, supponiamo che le espressioni di query includano spesso il campojsonPayload.request.status. Puoi configurare un indice personalizzato per un bucket che include 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 questo campo.

Utilizzando Google Cloud CLI o l'API Logging, puoi aggiungere indici personalizzati ai bucket di 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 affinché 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, segui questi passaggi:

  • Verifica di utilizzare la versione più recente della CLI gcloud. Per ulteriori informazioni, consulta Gestire i componenti della CLI Google Cloud.

  • Verifica di disporre di un ruolo Identity and Access Management con le seguenti autorizzazioni:

    Per informazioni dettagliate su questi ruoli, consulta Controllo dell'accesso con IAM.

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 al 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 aggiornandone uno esistente. Per ulteriori informazioni sulla configurazione dei bucket, consulta la sezione Configurare 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 del 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 che vengano archiviati i log.

    Ad esempio, se vuoi creare un bucket per il progetto my-project nella regione asia-east2, il parametro parent sarà simile a questo: 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'objeto IndexConfig.

Aggiorna 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.

Aggiornare 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, svolgi i seguenti 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.

Cancellare i campi indicizzati personalizzati

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.

Esegui query e visualizza i dati indicizzati

Per eseguire query sui dati inclusi nei campi indicizzati personalizzati, limita l'ambito della query al bucket contenente i campi indicizzati personalizzati e specifica la visualizzazione dei 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=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 del log appropriati e imposta resourceNames per selezionare i dati indicizzati.filter

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

Indicizzazione e tipi di campo

Il modo in cui configuri l'indicizzazione dei campi personalizzati può influire sul modo in cui i log vengono archiviati nei bucket dei log e su come vengono elaborate le query.

Al momento della scrittura

La registrazione tenta di utilizzare l'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 nella voce di log. Quando la voce di log viene archiviata nel bucket di log, il campo del log viene valutato in base al tipo di indice utilizzando queste regole:

  • Se il tipo di un campo corrisponde a quello dell'indice, i dati vengono aggiunti all'indice esattamente come sono.
  • 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 coercizione del tipo non riesce, i dati non vengono indicizzati. Quando la coercizione del tipo riesce, 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 funzionalità di registrazione 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 è 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 per un bucket è configurato un indice personalizzato, i comportamenti di corrispondenza allo schema differiscono quando si verificano entrambe le seguenti condizioni:

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

Considera i seguenti payload JSON:

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

Ora applica questo filtro a ogni riga:

jsonPayload.value > 20

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

  • Per "A", la registrazione osserva che il valore della chiave "value" è effettivamente 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é è il caso numerico.

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

Se il campo jsonPayload.value è incluso nell'indice personalizzato, la registrazione valuta questo vincolo utilizzando l'indice anziché la consueta logica di registrazione. 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" alfabeticamente. La voce "B" corrisponde, poiché la stringa "3" è maggiore di "20".
  • Se l'indice è di tipo intero, tutti i confronti sono confronti di interi.
    • La voce "B" non corrisponde, poiché "3" non è numericamente maggiore di "20". 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 gli indici personalizzati.

Caso limite di filtro

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

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 tu passi un valore intero:

jsonPayload.value > 50

Né A né B corrispondono, poiché né "12345" né "3" sono alfabeticamente superiori a "50".