Configura l'indicizzazione personalizzata

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

Panoramica

Le prestazioni delle query sono fondamentali per qualsiasi soluzione di logging. Con lo scale up dei carichi di lavoro e l'aumento dei volumi di log corrispondenti, l'indicizzazione dei dati dei log più utilizzati può ridurre i tempi 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, supponi che le espressioni di query spesso includano il campo jsonPayload.request.status. Potresti configurare un indice personalizzato per un bucket che include jsonPayload.request.status; qualsiasi query successiva sui dati di quel bucket farà riferimento ai dati indicizzati di jsonPayload.request.status se l'espressione di query include questo campo.

Utilizzando Google Cloud CLI o l'API Logging, puoi aggiungere indici personalizzati a bucket di log nuovi o esistenti. 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 affinché le modifiche vengano applicate alle tue 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 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 campo e un tipo di campo:

  • fieldPath: descrive il percorso specifico per il 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 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 come risorsa in cui creare il bucket: projects/PROJECT_ID/locations/LOCATION

    La variabile LOCATION fa riferimento all'area geografica 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 che includa 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.

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.

Aggiorna il percorso di un campo indicizzato personalizzato

Se devi correggere il percorso 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 corretto per un campo LogEntry.

Elenco di tutti i campi indicizzati di un bucket

Per elencare i dettagli di un bucket, inclusi i relativi campi indicizzati personalizzati:

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

Eseguire query e visualizzare dati indicizzati

Per eseguire una 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 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 log appropriati, poi imposta filter in modo da selezionare i dati indicizzati.

Per informazioni dettagliate sulla sintassi dei filtri, consulta la pagina relativa al linguaggio delle 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 sulle modalità di elaborazione delle 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 vengono 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 di log viene valutato in base al tipo di indice utilizzando queste regole:

  • Se il tipo di un campo è uguale al tipo dell'indice, i dati vengono aggiunti all'indice testualmente.
  • Se il tipo di campo è diverso da quello dell'indice, Logging tenta di forzare il tipo di indice (ad esempio, da intero in stringa).
    • Se la coercizione del tipo non va a buon fine, i dati non vengono indicizzati. Quando la coercizione del tipo ha esito positivo, i dati vengono indicizzati.

Al momento della query

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

Quando viene configurato un indice personalizzato per un bucket, i comportamenti di corrispondenza dello schema sono diversi 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 su quel campo.

Prendi in considerazione i seguenti payload JSON:

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

Ora applica questo filtro a:

jsonPayload.value > 20

Se nel campo jsonPayoad.value non è presente l'indicizzazione personalizzata, Logging applica la corrispondenza di tipo flessibile:

  • Per il valore "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. Quindi valuta "3" > "20" e restituisce "true", dal momento che questo è il caso alfanumerico.

Se il campo jsonPayload.value è incluso nell'indice personalizzato, Logging valuta questo vincolo utilizzando l'indice anziché la normale 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 è superiore a "20" in modo alfanumerico. 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.
    • Il valore "B" non corrisponde, perché "3" non è maggiore di "20" a livello numerico. La voce "A" corrisponde, poiché "12345" è maggiore di "20".

Questa differenza di comportamento è sottile e deve essere considerata durante la definizione e l'utilizzo degli indici personalizzati.

Applicazione di filtri a maiuscole e minuscole

Per l'indice di tipo intero jsonPayload.value, supponi di filtrare un valore stringa:

jsonPayload.value = "hello"

Se il valore della query non può essere forzato al tipo di indice, l'indice viene ignorato.

Tuttavia, supponi di passare un valore intero per un indice di tipo stringa:

jsonPayload.value > 50

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