Configurare l'indicizzazione personalizzata

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

Panoramica

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

Per migliorare le prestazioni delle query, Logging indicizza automaticamente 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 campo jsonPayload.request.status. Puoi configurare un indice personalizzato per un bucket che include jsonPayload.request.status; a qualsiasi query successiva i dati di quel bucket faranno riferimento jsonPayload.request.status 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 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 per 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 in bucket di log dopo la creazione o la modifica dell'indice; modifiche alle impostazioni 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 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. La 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 saperne di più sulla configurazione dei bucket, consulta Configurare i bucket di log.

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

gcloud

Utilizza la 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 come risorsa in cui per creare il bucket: projects/PROJECT_ID/locations/LOCATION

    La variabile LOCATION fa riferimento alla regione in cui vuoi che i log vengano archiviati.

    Ad esempio, se vuoi creare un bucket per il progetto my-project in nella regione asia-east2, il parametro parent sarebbe 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 la 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 le funzionalità di 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:

gcloud

Utilizza la 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. Nella Corpo della richiesta LogBucket, aggiorna l'oggetto IndexConfig in modo che fornisca 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 le funzionalità di 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: seguenti:

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 la 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 le funzionalità di 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 del al bucket che contiene i campi indicizzati personalizzati e specifica 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 tuoi 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 la classe entries.list. Imposta resourceNames per specificare il bucket e la visualizzazione log appropriati e impostare filter seleziona i tuoi dati indicizzati.

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 della voce del log. Quando la voce del 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. Con coercizione del tipo l'operazione 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 del 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.

Se per un bucket viene configurato un indice personalizzato, i comportamenti di corrispondenza dello schema differiscono quando entrambe le condizioni sono soddisfatte:

  • 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:

jsonPayload.value > 20

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

  • Per "A", Logging osserva che il valore del "value" il tasto è un numero intero e che il vincolo "20" può essere convertito numero intero. Logging quindi valuta 12345 > 20 e restituisce "vero" perché questo è il caso numerico.

  • Per "B", Logging osserva che il valore del "value" chiave è in realtà una stringa. Valuta quindi "3" > "20" e restituisce "true", poiché questo è il caso in formato 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 tra stringhe.
    • La lettera "A" voce 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.
    • La "B" voce non corrisponde, poiché "3" non è superiore a "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 usando indici personalizzati.

Filtro caso limite

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

jsonPayload.value = "hello"

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

Supponiamo, però, che per un indice di tipo stringa venga passato un valore intero:

jsonPayload.value > 50

Né A né B corrispondono, né "12345" né "3" è maggiore in modo alfanumerico di "50".