Linguaggio di query di Logging

Questo documento descrive, a livello generale, il linguaggio di query di Logging che utilizzi per eseguire query e filtrare i dati di Cloud Logging.

Per informazioni dettagliate sulla progettazione del linguaggio di query di Logging, consulta le specifiche formali dell'API di Google per l'applicazione di filtri.

Per esempi di query comuni che potresti voler utilizzare, consulta Query di esempio utilizzando Esplora log.

Panoramica

Puoi utilizzare il linguaggio di query di Logging in Esplora log nella console Google Cloud, nell'API Logging o nell'interfaccia a riga di comando. Puoi utilizzare il linguaggio di query di Logging per eseguire query sui dati e scrivere filtri per creare sink e metriche basate su log.

Una query è un'espressione booleana che specifica un sottoinsieme di tutte le voci di log nella risorsa Google Cloud selezionata, come un progetto o una cartella Google Cloud.

Puoi creare query basate sul campo indicizzato LogEntry utilizzando gli operatori logici AND e OR. Utilizzando il campo resource.type nei seguenti esempi, la grammatica del linguaggio di query di Logging è simile a questa:

  • Restrizione semplice: resource.type = "gae_app"

  • Limitazione congiuntiva: resource.type = "gae_app" AND severity = "ERROR"

  • Limitazione digiuntiva: resource.type = "gae_app" OR resource.type = "gce_instance"

    • In alternativa: resource.type = ("gae_app" OR "gce_instance")

  • Espressione congiuntiva/disgiuntiva complessa: resource.type = "gae_app" AND (severity = "ERROR" OR "error")

Di seguito è riportato un semplice esempio di query:

resource.type = "gce_instance" AND
severity >= "ERROR" AND
NOT textPayload:robot

Questa query corrisponde alle voci di log di Compute Engine con valori di gravità almeno ERROR e il cui campo textPayload non contiene la stringa robot al suo interno. I confronti tra stringhe non fanno distinzione tra maiuscole e minuscole. I nomi resource, severity e textPayload sono definiti nel tipo LogEntry.

Notazione della sintassi

Le seguenti sezioni forniscono una panoramica della sintassi del linguaggio delle query di Logging e discutono in dettaglio come sono strutturate le query e come viene eseguita la corrispondenza. Alcuni esempi utilizzano i commenti per fornire un testo esplicativo.

Tieni presente quanto segue:

  • La lunghezza di una query non può superare i 20.000 caratteri.

  • Il linguaggio di query di Logging non è sensibile alle maiuscole, ad eccezione delle espressioni regolari.

Riepilogo della sintassi

La sintassi del linguaggio di query di Logging può essere considerata in termini di query e confronti.

Una query è una stringa contenente un'espressione:

expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }

Un confronto può essere un singolo valore o un'espressione booleana:

"The cat in the hat"
resource.type = "gae_app"

La prima riga è un esempio di confronto con un valore singolo. Questi tipi di confronti sono limitazioni globali. Ogni campo di una voce di log viene confrontato con il valore tramite l'operatore implicito has. Per questo esempio, se un campo qualsiasi in un LogEntry, o se il relativo payload contiene la frase "The cat in the hat", il confronto ha esito positivo.

La seconda riga è un esempio di confronto, ovvero un'espressione booleana nel formato [FIELD_NAME] [OP] [VALUE]. Gli elementi del confronto sono descritti di seguito:

  • [FIELD_NAME] è un campo in una voce di log. Ad esempio, resource.type.

  • [OP] è un operatore di confronto. Ad esempio, =.

  • [VALUE] è un numero, una stringa, una funzione o un'espressione tra parentesi. Ad esempio, "gae_app". Per i valori null JSON, utilizza NULL_VALUE.

Operatori booleani

Gli operatori booleani AND e OR sono operatori di cortocircuito. L'operatore NOT ha la precedenza più alta, seguito da OR e AND in questo ordine. Ad esempio, le seguenti due espressioni sono equivalenti:

"a" OR NOT "b" AND NOT "c" OR "d"
("a" OR (NOT "b")) AND ((NOT "c") OR "d")

Puoi omettere l'operatore AND tra i confronti. Puoi anche sostituire l'operatore NOT con l'operatore - (meno). Ad esempio, le seguenti due query sono uguali:

a="b" AND c="d" AND NOT e="f"
a="b" c="d" -e="f"

Questa documentazione utilizza sempre i criteri AND e NOT.

Per tutti i filtri eccetto quelli utilizzati dalle viste log, puoi utilizzare gli operatori AND, OR e NOT. Le visualizzazioni log supportano solo le operazioni AND e NOT.

Per combinare le regole AND e OR nella stessa espressione, devi nidificare le regole utilizzando le parentesi. Se non utilizzi le parentesi, la query potrebbe non funzionare come previsto.

Gli operatori booleani devono sempre contenere le lettere maiuscole. and, or e not in minuscolo vengono analizzati come termini di ricerca.

Confronti

I confronti hanno il seguente formato:

[FIELD_NAME] [OP] [VALUE]

Gli elementi del confronto sono descritti di seguito:

  • [FIELD_NAME]: nome del percorso di un campo in una voce di log. Esempi di nome del campo:

    resource.type
resource.labels.zone
resource.labels.project_id
insertId
jsonPayload.httpRequest.protocol
labels."compute.googleapis.com/resource_id"

    Se un componente del nome di un percorso contiene caratteri speciali, il nome del percorso deve essere racchiuso tra virgolette. Ad esempio, compute.googleapis.com/resource_id deve essere racchiuso tra virgolette perché contiene una barra /.

    Per maggiori dettagli, consulta la sezione sugli identificatori dei percorsi dei campi in questo documento.

  • [OP]: è un operatore di confronto, uno dei seguenti:

    =           -- equal
!=          -- not equal
> < >= <=   -- numeric ordering
:           -- "has" matches any substring in the log entry field
=~          -- regular expression search for a pattern
!~          -- regular expression search not for a pattern

Per informazioni su come eseguire ricerche nelle voci di log utilizzando le espressioni regolari, consulta Utilizzo delle espressioni regolari.

  • [VALUE]: rappresenta un numero, una stringa, una funzione o un'espressione tra parentesi. Le stringhe vengono utilizzate per rappresentare il testo arbitrario, oltre a valori booleani, di enumerazione e di stringa di byte. [VALUE] viene convertito nel tipo di campo prima del confronto. Per i valori null JSON, utilizza NULL_VALUE.

Per filtrare in base a un valore JSON null, utilizza la seguente sintassi:

jsonPayload.field = NULL_VALUE      -- includes "field" with null value
NOT jsonPayload.field = NULL_VALUE  -- excludes "field" with null value

Se [VALUE] è una combinazione booleana di confronti tra parentesi, il nome del campo e l'operatore di confronto vengono applicati a ciascun elemento. Ad esempio:

jsonPayload.cat = ("longhair" OR "shorthair")
jsonPayload.animal : ("nice" AND "pet")

Il primo confronto verifica che il campo cat abbia il valore "longhair" o "shorthair". Il secondo verifica che il valore del campo animal contenga entrambe le parole "nice" e "pet", in qualsiasi ordine.

Identificatori dei percorsi dei campi

Tutte le voci di log sono istanze di tipo LogEntry. L'identificatore che rappresenta (o inizia) il lato sinistro di un confronto deve essere un campo definito nel tipo LogEntry. Per maggiori dettagli sui possibili identificatori e sui relativi valori, consulta Tipo LogEntry.

Ecco l'elenco attuale dei campi delle voce di log. Ogni campo è seguito dal livello successivo di nomi per quel campo, se applicabile:

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status e userAgent }
  • insertId
  • jsonPayload { variable }
  • labels { variable }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, variabile }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

Di seguito sono riportati alcuni esempi di identificatori di percorso del campo che puoi utilizzare nei confronti:

  • resource.type: se il primo identificatore di percorso è resource, l'identificatore successivo deve essere un campo del tipo MonitoredResource.

  • httpRequest.latency: se il primo identificatore di percorso è httpRequest, l'identificatore successivo deve essere un campo nel tipo HttpRequest.

  • labels.[KEY] Se il primo identificatore di percorso è labels, l'identificatore successivo, [KEY], deve essere una delle chiavi delle coppie chiave-valore presenti nel campo labels.

  • logName: poiché il campo logName è una stringa, non puoi utilizzarlo per nome di sottocampo.

Quando esegui una query su campi map o struct, devi mantenere maiuscole e minuscole e la formattazione delle lettere delle chiavi nell'espressione.

Ad esempio, jsonPayload è un campo di struct, quindi un nome di campo nidificato all'interno di jsonPayload come jsonPayload.end_time è diverso da jsonPayload.endTime. Analogamente, per un campo mappa come labels, la chiave di etichetta labels.env_name è diversa da labels.envName. Al contrario, quando esegui una query sul normale campo del buffer di protocollo protoPayload, non è necessario conservare maiuscole e minuscole.

Per informazioni sui tipi di campo LogEntry, consulta la documentazione di riferimento su google.logging.v2.

Caratteri speciali

Se un campo LogEntry contiene caratteri speciali, il campo del log deve essere racchiuso tra virgolette. Ad esempio:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

Per l'elenco dei caratteri speciali, consulta la sezione string in Valori e conversioni.

Per ulteriori informazioni sull'utilizzo degli identificatori di percorso dei campi che fanno riferimento a oggetti o array, consulta Tipi di oggetti e array in questo documento.

Tipi di risorse monitorate

Per query più rapide, specifica un tipo di risorsa monitorata. Per un elenco dei tipi di risorse, consulta Tipi di risorse monitorate.

Ad esempio, le VM di Compute Engine utilizzano il tipo di risorsa gce_instance e le istanze Amazon EC2 utilizzano aws_ec2_instance. L'esempio seguente mostra come limitare le query a entrambi i tipi di VM:

resource.type = ("gce_instance" OR "aws_ec2_instance")

I valori del tipo di risorsa monitorata nei log sono indicizzati. Se usi le corrispondenze di sottostringhe, le query saranno più lente.

Campi mancanti

Se utilizzi il nome di un campo in una query e tale campo non viene visualizzato in una voce di log, significa che il campo è mancante, undefined o defaulted:

  • Se il campo fa parte del payload della voce di log (jsonPayload o protoPayload) o se è in un'etichetta nella sezione labels della voce di log, il campo manca. L'utilizzo di un campo mancante non mostra un errore, ma tutti i confronti che utilizzano i campi mancanti non vengono visualizzati correttamente.

    Esempi: jsonPayload.nearest_store, protoPayload.name.nickname

  • Se il campo viene definito nel tipo LogEntry, il campo è defaulted. I confronti vengono eseguiti come se il campo fosse presente e avesse il suo valore predefinito.

    Esempi: httpRequest.remoteIp, trace, operation.producer

  • In caso contrario, il campo è undefined, un errore che viene rilevato prima dell'utilizzo della query.

    Esempi: thud, operation.thud, textPayload.thud

Per verificare se esiste un campo mancante o predefinito senza testare un determinato valore nel campo, utilizza il confronto :*. Ad esempio, il seguente confronto ha esito positivo se il campo operation.id è presente esplicitamente in una voce di log:

operation.id:*

Osserva il comportamento delle seguenti query:

  • Quando utilizzi l'operatore booleano NOT su un campo mancante, il risultato è TRUE:

    -- Returns TRUE
NOT missingField=foo

  • Quando utilizzi l'operatore di confronto diverso da != su un campo mancante, il risultato è FALSE:

    -- Returns FALSE
missingField!=foo

Tipi di oggetti e array

Ogni campo di voce di log può contenere un scalar, un oggetto o un array.

  • Un campo scalar memorizza un singolo valore, come 174.4 o -1. Anche un elemento string è considerato uno scalare. Anche i campi che possono essere convertiti in (o da) una stringa, come Duration e Timestamp, sono di tipo scalare.

  • Un tipo di oggetto archivia una raccolta di valori denominati, come il seguente valore JSON:

    {"age": 24, "height": 67}

    Puoi fare riferimento al valore all'interno di un oggetto. Ad esempio, se jsonPayload.x contenesse il valore precedente, jsonPayload.x.age avrebbe il valore 24.

  • Un campo array memorizza un elenco di valori, tutti dello stesso tipo. Ad esempio, un campo relativo alle misurazioni potrebbe avere un array di numeri:

    {8.5, 9, 6}

    Quando vengono eseguiti confronti e [FIELD_NAME] è un campo array, ogni membro dell'array viene confrontato con [VALUE] e i risultati vengono uniti utilizzando l'operatore OR. Ad esempio, se jsonPayload.shoeSize è un campo array che memorizza {8.5, 9, 6}, il confronto:

    jsonPayload.shoeSize < 7

    equivale a:

    8.5 < 7 OR 9 < 7 OR 6 < 7

    In questo esempio, il confronto complessivo ha valore positivo.

Valori e conversioni

Il primo passaggio nella valutazione di un confronto è convertire il valore sul lato destro nel tipo di campo di voce di log. I tipi di campo scalari sono consentiti nei confronti, insieme a due tipi aggiuntivi i cui valori sono rappresentati come stringhe: Duration e Timestamp. Per un elenco dei tipi scalari, consulta l'elenco dei tipi di buffer di protocollo scalari. La seguente tabella spiega quali valori possono essere convertiti nei tipi di campi di log:

Tipo di campo Valore della query consentito
bool

"True" o "false" in qualsiasi lettera maiuscola. Esempi: "True", "true"
bytes

Una stringa contenente qualsiasi sequenza di byte. Esempio: "\377\377".
Duration

Una stringa contenente un numero decimale firmato seguito da una delle unità "ns", "us", "ms", "s", "m" o "h". Le durate sono precise fino a nanosecondi. Esempio: "3.2s".
enum

Il nome di un valore letterale di tipo di enumerazione, senza distinzione tra maiuscole e minuscole. Esempi: "WARNING", che è un valore di tipo LogSeverity.
double

Qualsiasi numero, con o senza un segno e una parte esponente o le stringhe con valori speciali "NaN", "-Infinito" e "Infinito" (in maiuscolo o meno). Esempi: "-3.2e-8", "nan".
intNN

Qualsiasi numero intero firmato che non superi le dimensioni del tipo. Esempio: "-3".
string

Qualsiasi stringa contenente testo ASCII a 7 bit o con codifica UTF-8. Le virgolette incorporate devono essere precedute da una barra rovesciata.

I valori delle stringhe devono essere racchiusi tra virgolette per eseguire l'escape dei seguenti caratteri speciali:

  • Stringhe che iniziano con + (più), - (meno) o . (punto).

  • Stringhe con ~ (tilde), = (uguale a), () (parentesi), : (due punti), > (maggiore di), < (minore di), , (virgola), . (punto) o * (asterisco).

  • Qualsiasi sequenza di escape, ad esempio \t.
Timestamp

Una stringa in formato RFC 3339 o ISO 8601. Esempi: "2014-10-02T15&colon;01&colon;23.045Z" (RFC 3339), "2014-10-02" (ISO 8601). Nelle espressioni di query, i timestamp nel formato RFC 3339 possono specificare un fuso orario con "Z" o ±hh:mm. I timestamp sono rappresentati con una precisione in nanosecondi.
uintNN

Qualsiasi numero intero senza segno che non superi le dimensioni del tipo. Esempio: "1234".

Se un tentativo di conversione non va a buon fine, il confronto non va a buon fine.

Quando una conversione richiede una stringa, puoi utilizzare anche un numero o testo senza virgolette se non contiene caratteri speciali come spazi e operatori. Analogamente, quando una conversione richiede un numero, puoi utilizzare una stringa il cui contenuto è un numero.

I tipi intNN e uintNN rappresentano tipi interi di varie dimensioni, ad esempio int32 e uint64. Quando scrivi un valore da convertire in un numero intero a 64 bit, lo scrivi come stringa, ad esempio "9223372036854775807".

Tipi di campi di log

Ecco come viene determinato il tipo di campo di voce di log:

  • I campi di log definiti nel tipo LogEntry e nel tipo di componente sono campi del buffer di protocollo. I campi del buffer del protocollo hanno tipi espliciti.

  • I campi di log che fanno parte degli oggetti protoPayload sono anche campi del buffer di protocollo e hanno tipi espliciti. Il nome del tipo di buffer di protocollo viene memorizzato nel campo "@type" di protoPayload. Per saperne di più, consulta la pagina relativa alla mappatura di JSON.

    Quando applichi un filtro in base a un campo associato al tipo di messaggio Any, il campo value viene trasferito automaticamente. Pertanto, non includerlo nella query. Per ulteriori informazioni, consulta la sezione Risoluzione dei problemi.

  • I campi di log all'interno di jsonPayload hanno tipi dedotti dal valore del campo quando viene ricevuta la voce di log:

    • I campi i cui valori sono numeri senza virgolette sono di tipo double.
    • I campi con valori true o false hanno il tipo bool.
    • I campi con valori sono stringhe hanno il tipo string.

    I numeri interi lunghi (64 bit) vengono archiviati in campi stringa, perché non possono essere rappresentati esattamente come valori double.

  • I tipi Duration e Timestamp vengono riconosciuti solo nei campi del buffer di protocollo. Altrove, questi valori sono archiviati in campi stringa.

Commenti

I commenti iniziano con due trattini (--) e l'eventuale testo che segue questi trattini viene ignorato fino alla fine della riga. I commenti possono essere inseriti all'inizio di un filtro, tra i termini e alla fine di un filtro.

Puoi utilizzare i commenti nei seguenti casi:

  • Per annotare i filtri complessi con informazioni sulla funzione di una clausola:

     -- All of our target users are emitted by Compute Engine instances.
 resource.type = "gce_instance"
 -- Looking for logs from "alex".
 jsonPayload.targetUser = "alex"

  • Per abilitare o disabilitare rapidamente una clausola aggiungendo o rimuovendo il prefisso dei commenti:

     resource.type = "gce_instance"
 -- jsonPayload.targetUser = "alex"
 jsonPayload.targetUser = "kiran"
 -- jsonPayload.targetUser = "sasha"

Operatori di confronto

Il significato degli operatori di uguaglianza (=, !=) e disuguaglianza (<, <=, >, >=) dipende dal tipo sottostante del nome del campo a sinistra.

  • Tutti i tipi numerici: uguaglianza e disuguaglianza hanno il loro normale significato per i numeri.
  • bool: l'uguaglianza indica lo stesso valore booleano. La disuguaglianza è definita da true>false.
  • enum: l'uguaglianza indica lo stesso valore di enumerazione. La disuguaglianza utilizza i valori numerici sottostanti dei valori letterali di enumerazione.
  • Duration: l'uguaglianza indica la stessa durata della durata. La disuguaglianza si basa sulla durata della durata. Esempio: come durate, "1s">"999ms".
  • Timestamp: l'uguaglianza indica lo stesso istante nel tempo. Se a e b sono Timestamp valori, a < b significa che a è antecedente nel tempo di b.
  • bytes: gli operandi vengono confrontati byte per byte, da sinistra a destra.
  • string: i confronti ignorano le lettere maiuscole e minuscole. In particolare, entrambi gli operandi vengono normalizzati prima mediante la normalizzazione Unicode NFKC_CF e poi utilizzano i confronti lessicografici. Tuttavia, le ricerche tramite espressioni regolari non sono normalizzate. Per ulteriori informazioni sulla ricerca nelle voci di log utilizzando le espressioni regolari, consulta Utilizzo delle espressioni regolari.

L'operatore di sottostringa (:) è applicabile a string e bytes ed è gestito come l'uguaglianza, ad eccezione del fatto che l'operando destro deve corrispondere solo a una parte del campo a sinistra. Le corrispondenze delle sottostringhe nei campi indicizzati non sfruttano gli indici di log.

Limitazioni globali

Se il confronto è composto da un solo valore, si parla di limitazione globale. Logging utilizza l'operatore has (:) per determinare se un campo in una voce di log, o se il relativo payload, contiene la limitazione globale. In caso affermativo, il confronto ha esito positivo.

La query più semplice scritta in termini di restrizione globale è un singolo valore:

"The Cat in The Hat"

Puoi combinare le restrizioni globali utilizzando gli operatori AND e OR per una query più interessante. Ad esempio, se vuoi visualizzare tutte le voci di log con un campo contenente cat e un campo contenente hat o bat, scrivi la query come:

("cat" AND ("hat" OR "bat"))

In questo caso, sono presenti tre limitazioni globali: cat, hat e bat. Queste limitazioni globali vengono applicate separatamente e i risultati vengono combinati, proprio come se l'espressione fosse stata scritta senza parentesi.

Una restrizione globale è un modo semplice per eseguire query nei log per un determinato valore. Ad esempio, se nel log delle attività cerchi voci contenenti qualsiasi menzione di GCE_OPERATION_DONE, puoi utilizzare la seguente query:

logName = "projects/my-project-id/logs/compute.googleapis.com%2Factivity_log" AND
"GCE_OPERATION_DONE"

Sebbene le restrizioni globali siano semplici, possono essere lente; per ulteriori informazioni, consulta la sezione Trovare rapidamente le voci di log in questo documento.

Funzioni

Puoi utilizzare le funzioni integrate come limitazioni globali nelle query:

function = identifier ( [ argument { , argument } ] )

dove argument è un valore, un nome di campo o un'espressione tra parentesi. Le funzioni sono descritte nelle sezioni seguenti.

log_id

La funzione log_id restituisce le voci di log corrispondenti all'argomento [LOG_ID] specificato nel campo logName:

log_id([LOG_ID])

Ad esempio, la seguente query restituisce tutte le voci di log con un cloudaudit.googleapis.com%2Factivity [LOG_ID]:

log_id("cloudaudit.googleapis.com/activity")

trasmettere

La funzione cast accetta due parametri: il campo LogEntry da trasmettere e il tipo di dati in cui viene convertito il campo:

cast([FIELD], [TYPE][, OPTION])

I parametri dell'espressione precedente sono definiti come segue:

  • [FIELD]: il nome di un campo nella voce di log, come logName o jsonPayload.a_field.

  • [TYPE]: il tipo di dati, ad esempio STRING, INT64, FLOAT64, BOOL.

    • TIMESTAMP oppure DURATION: alcuni tipi di dati offrono opzioni aggiuntive, come la specifica di un fuso orario del database dei fusi orari IANA per il tipo di dati TIMESTAMP.

Ad esempio, la seguente query trasmette il campo timestamp in STRING e specifica il fuso orario America/New_York:

cast(timestamp, STRING, TIMEZONE("America/New_York")) =~ "^2023-01-02.*"

regexp_extract

Utilizza la funzione regexp_extract per trovare la prima sottostringa che corrisponde a un'espressione regolare:

REGEXP_EXTRACT([FIELD], [REGULAR_EXPRESSION])

Nell'espressione precedente, i campi sono definiti come segue:

  • [FIELD]: il nome di un campo nella voce di log, come logName o jsonPayload.a_field.
  • [REGULAR_EXPRESSION]: l'espressione regolare RE2 che deve contenere un gruppo di acquisizione ((...)). È necessario utilizzare un gruppo non di acquisizione (?:...) se è necessario un raggruppamento aggiuntivo per l'espressione regolare. Più gruppi di acquisizione o nessun gruppo di acquisizione generano un errore.

Puoi concatenare le funzioni cast e regexp_extract:

CAST(REGEXP_EXTRACT(CAST(timestamp, STRING), "\\d+:\\d+:\\d+\\.(\\d+)"), INT64) < 500

L'esempio precedente trasmette il campo timestamp come stringa. L'espressione regolare acquisisce la parte in millisecondi della stringa timestamp e la trasforma in un numero intero per eseguire un confronto numerico. Vengono restituite tutte le voci di log che contengono timestamp in cui il campo dei millisecondi è inferiore a 500.

origine

La funzione source corrisponde alle voci di log di una determinata risorsa nella gerarchia di organizzazioni, cartelle e progetti Google Cloud.

La funzione source non corrisponde alle risorse figlio. Ad esempio, l'utilizzo di source(folders/folder_123) trova i log della risorsa folder_123 e non i log delle risorse del progetto Google Cloud in folder_123.

Per eseguire una query sui log a un determinato livello di risorsa, utilizza la seguente sintassi:

source(RESOURCE_TYPE/RESOURCE_ID)
Risorsa Query di esempio
Organizzazione source(organizations/ORGANIZATION_ID)
Cartella source(folders/FOLDER_ID)
Progetti Google Cloud source(projects/PROJECT_ID)

esempio

La funzione sample seleziona una frazione del numero totale di voci di log:

sample([FIELD], [FRACTION])

[FIELD] è il nome di un campo nella voce di log, come logName o jsonPayload.a_field. Il valore del campo determina se la voce di log è presente nel campione. Il tipo di campo deve essere una stringa o un valore numerico. Impostare [FIELD] su insertId è una buona scelta, perché ogni voce di log ha un valore diverso per quel campo.

[FRACTION] è la frazione delle voci di log con valori da includere per [FIELD]. È un numero maggiore di 0,0 e non superiore a 1,0. Ad esempio, se specifichi 0.01, il campione contiene circa l'1% di tutte le voci di log con valori per [FIELD]. Se [FRACTION] è 1, vengono scelte tutte le voci di log con valori per [FIELD].

Esempio: la seguente query restituisce il 25% delle voci di log dal log syslog:

logName = "projects/my-project/logs/syslog" AND sample(insertId, 0.25)

Dettagli: un algoritmo deterministico, basato sull'hashing, viene utilizzato per determinare se una voce di log è stata inclusa o esclusa dal campione. L'accuratezza del campione risultante dipende dalla distribuzione dei valori sottoposti ad hashing. Se i valori sottoposti ad hashing non sono distribuiti uniformemente, il campione risultante può essere distorto. Nel peggiore dei casi, quando [FIELD] contiene sempre lo stesso valore, il campione risultante contiene [FRACTION] di tutte le voci di log o nessuna.

Se [FIELD] compare in una voce di log:

  • Viene calcolato un hash del valore.
  • Il valore hash, ovvero un numero, viene diviso per il valore hash massimo possibile.
  • Se la frazione risultante è inferiore o uguale a [FRACTION], la voce di log viene inclusa nel campione, altrimenti viene esclusa dal campione.

Se [FIELD] non viene visualizzato in una voce di log:

  • Se [FIELD] fa parte del payload della voce di log o delle sezioni labels, la voce di log non viene selezionata per il campione, anche se [FRACTION] è 1.
  • In caso contrario, la voce di log viene trattata come se [FIELD] si trovasse nella voce di log e il valore di [FIELD] fosse il valore predefinito. Il valore predefinito è determinato dal tipo LogEntry. Per ulteriori informazioni sui campi mancanti e predefiniti, consulta la sezione Campi mancanti in questo documento.

Per escludere dall'esempio le voci di log con campi predefiniti, utilizza l'operatore field-exists (:*). La seguente query produce un campione dell'1% di voci di log che hanno fornito esplicitamente un valore per field:

field:* AND sample(field, 0.01)

ip_in_net

La funzione ip_in_net determina se un indirizzo IP in una voce di log è contenuto in una subnet. Puoi utilizzarlo per capire se una richiesta proviene da una sorgente interna o esterna. Ad esempio:

ip_in_net([FIELD], [SUBNET])

[FIELD] è un campo con valori stringa nella voce di log che contiene un indirizzo o un intervallo IP. Il campo può essere ripetuto, nel qual caso solo uno dei campi ripetuti deve contenere un indirizzo o un intervallo all'interno della subnet.

[SUBNET] è una costante stringa per un indirizzo o un intervallo IP. È un errore se [SUBNET] non è un indirizzo o un intervallo IP legale, come descritto più avanti in questa sezione.

Esempio: la query seguente verifica un indirizzo IP nel payload delle voci di log dal log my_log:

logName = "projects/my_project/logs/my_log" AND
ip_in_net(jsonPayload.realClientIP, "10.1.2.0/24")

Dettagli: se, in una voce di log, [FIELD] è mancante, è impostato come predefinito o non contiene un indirizzo o un intervallo IP legale, la funzione restituisce false. Per ulteriori informazioni sui campi mancanti e predefiniti, consulta la sezione Campi mancanti in questo documento.

Di seguito sono riportati alcuni esempi di indirizzi e intervalli IP supportati:

  • IPv4: 10.1.2.3
  • Subnet IPv4: 10.1.2.0/24
  • IPv6 CIDR: 1234:5678:90ab:cdef:1234:5678:90ab:cdef
  • Subnet IPv6 CIDR: 1:2::/48

SEARCH funzione

Puoi utilizzare la funzione SEARCH integrata per trovare stringhe nei dati di log:

SEARCH([query])
SEARCH([field], [query])

Entrambe le forme della funzione SEARCH contengono un argomento query, che deve essere formattato come valore letterale stringa. Nel primo modulo viene cercata l'intera voce di log. Nel secondo modulo, devi specificare il campo della voce di log da ricercare.

Devi specificare il campo query. Se questo campo non viene specificato, viene restituito un errore.

Quando la funzione SEARCH viene elaborata, la stringa query viene elaborata da un analizzatore di testo che suddivide la stringa in token. Cloud Logging esegue sempre confronti senza distinzione tra maiuscole e minuscole, anche per i token con wrapping. Questo comportamento è diverso da quello di BigQuery, che conserva le maiuscole e le minuscole nei token con apici inversi. Per informazioni sulle regole dell'analizzatore, consulta il documento di BigQuery Regole dell'analizzatore di testo.

Quando crei una ricerca, considera quanto segue:

  • I token non fanno distinzione tra maiuscole e minuscole. Le seguenti funzioni producono gli stessi risultati:

    SEARCH("world")
SEARCH("World")

    Le funzioni precedenti corrispondono a una voce di log quando un singolo campo contiene il token "world". Poiché SEARCH esegue corrispondenze esatte e non corrispondenze di sottostringhe, le funzioni precedenti non corrispondono a un campo il cui valore è "worldwide".

  • Se non specifichi il campo da cercare, la funzione SEARCH troverà una voce di log che contiene tutti i token. Tuttavia, l'ordine dei token non è importante e non è necessario che siano presenti nello stesso campo della voce di log.

    Le seguenti funzioni producono gli stessi risultati e corrispondono a una voce di log contenente i token "hello" e "world":

    SEARCH("hello world")
SEARCH("World hello")

  • Se specifichi il campo da cercare, la funzione SEARCH eseguirà la ricerca solo in quel campo. Una corrispondenza si verifica quando il campo contiene tutti i token, ma l'ordine dei token non è importante.

    Le seguenti funzioni producono una corrispondenza solo quando il campo textPayload contiene i token "hello" e "world":

    SEARCH(textPayload, "hello world")

  • Per imporre una corrispondenza esatta e senza distinzione tra maiuscole e minuscole in una frase, racchiudi la frase tra apici inversi. Ad esempio, le seguenti funzioni corrispondono alla stringa "hello world":

    SEARCH("`hello world`")
SEARCH("`Hello World`")
SEARCH("`HELLO WORLD`")

    Poiché gli apici inversi vengono utilizzati nelle funzioni seguenti, producono risultati diversi:

    SEARCH("`hello world`")
SEARCH("`world hello`")

Il linguaggio di query di Logging supporta diversi modi in cui puoi cercare i dati dei log. Quando cerchi una stringa, è più efficiente utilizzare la funzione SEARCH che eseguire una ricerca globale o una ricerca di sottostringhe. Tuttavia, non puoi utilizzare la funzione SEARCH per associare i campi non di testo. Per indicazioni sull'esecuzione delle operazioni di ricerca, consulta Ridurre al minimo le ricerche globali e di sottostringhe.

Ricerca per ora

Nell'interfaccia puoi impostare limiti specifici per la data e l'ora delle voci di log da visualizzare. Ad esempio, se aggiungi le seguenti condizioni alla query, l'anteprima mostra esattamente le voci di log nel periodo di 30 minuti indicato e non potrai scorrere al di fuori di questo intervallo di date:

timestamp >= "2016-11-29T23:00:00Z"
timestamp <= "2016-11-29T23:30:00Z"

Quando scrivi una query con un timestamp, devi utilizzare date e ore nel formato mostrato sopra.

Puoi anche cercare le voci di log utilizzando le scorciatoie di timestamp. Ad esempio, puoi inserire una data con un operatore di confronto per visualizzare tutte le voci di log dopo un determinato giorno:

timestamp > "2016-11-29"

Utilizzo delle espressioni regolari

Puoi utilizzare espressioni regolari per creare query e filtri per sink, metriche e ovunque vengano utilizzati i filtri di log. Puoi utilizzare le espressioni regolari nel Query Builder e con Google Cloud CLI.

Un'espressione regolare è una sequenza di caratteri che definiscono una ricerca. Il linguaggio di query di Logging utilizza la sintassi RE2. Per una spiegazione completa della sintassi RE2, consulta il wiki RE2 su GitHub.

Le query di espressioni regolari hanno le seguenti caratteristiche:

  • Solo i campi di tipo stringa possono essere abbinati a un'espressione regolare.

  • La normalizzazione delle stringhe non viene eseguita; ad esempio, kubernetes non viene considerato uguale a KUBERNETES. Per ulteriori informazioni, consulta la sezione Operatori di confronto.

  • Le query sono sensibili alle maiuscole e non sono ancorate per impostazione predefinita.

  • Gli operatori booleani possono essere utilizzati tra più espressioni regolari sul lato destro dell'operatore di confronto delle espressioni regolari, =~ e !~.

Una query con espressione regolare ha la seguente struttura:

Utilizza uno schema:

jsonPayload.message =~ "regular expression pattern"

Non corrisponde a un pattern:

jsonPayload.message !~ "regular expression pattern"

=~ e !~ modificano la query in una query con espressione regolare e il pattern per cui vuoi trovare una corrispondenza deve essere tra virgolette. Per eseguire query relative a pattern che contengono virgolette doppie, inserisci l'escape delle virgolette con una barra rovesciata.

Esempi di query sui log utilizzando espressioni regolari

Tipo di query Esempio
Query standard sourceLocation.file =~ "foo"
Query con ricerca senza distinzione tra maiuscole e minuscole labels.subnetwork_name =~ "(?i)foo"
Query contenente virgolette jsonPayload.message =~ "field1=\"bar.*\""
Query che utilizza un valore booleano or labels.pod_name =~ "(foo|bar)"
Query utilizzando gli ancoraggi logName =~ "/my%2Flog$"
La query non corrisponde a un pattern labels.pod_name !~ "foo"
Query con operatore booleano labels.env =~ ("^prod.*server" OR "^staging.*server")
Query che inizia con un valore logName =~ "^foo"
Query che termina con un valore logName =~ "foo$"

Individuazione rapida delle voci di log

Per trovare le voci di log in modo più efficiente:

  • Esegui una query utilizzando campi indicizzati.
  • Riduci al minimo il numero di voci di log da ricercare.

Usare campi indicizzati

Logging indicizza sempre i seguenti campi LogEntry:

Puoi anche aggiungere campi indicizzati personalizzati a qualsiasi bucket di log.

Le sezioni successive spiegano come utilizzare i campi indicizzati per ridurre al minimo il numero di voci di log da cercare.

Ottimizza le query

Velocizza le ricerche riducendo il numero di log, il numero di voci di log o la durata delle ricerche. Meglio ancora, puoi ridurle tutti e tre.

Esempio: utilizzare il nome di log corretto

Specifica il log contenente le voci di log che ti interessano. Assicurati di conoscere il nome effettivo del log ispezionando una delle voci di log. Ad esempio, l'anteprima mostra che esiste un log nella sezione di Compute Engine denominata "activity". A un'analisi più approfondita delle voci dell'audit log dell'attività di amministrazione, il log in realtà è denominato "cloudaudit.googleapis.com/activity".

Il confronto che segue non è corretto. Non corrisponde a nulla, perché utilizza il nome log sbagliato:

logName = "projects/my-project-id/logs/activity"   -- WRONG!

Il confronto che segue è corretto. Sceglie le voci di log dalle voci degli audit log dell'attività di amministrazione. Devi eseguire la codifica URL per il nome log, come illustrato di seguito:

logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

Esempio: scegliere le voci di log corrette

Se sai che le voci di log desiderate provengono da una determinata istanza VM, specificale. Cerca i nomi delle etichette corretti esaminando una delle voci di log che vuoi cercare. Nell'esempio seguente, instance_id è una delle etichette indicizzate:

resource.type = "gce_instance" AND
resource.labels.instance_id = "6731710280662790612"
logName = "projects/my-project-id/logs/cloudaudit.googleapis.com%2Factivity"

Esempio: scegliere il periodo di tempo giusto

Specifica un periodo di tempo in cui eseguire la ricerca. Un modo rapido per determinare i timestamp utili nel formato RFC 3339 consiste nell'utilizzare il comando date GNU/Linux:

$ date --rfc-3339=s
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

Utilizza i valori di questi timestamp nelle seguenti query. Per creare un timestamp accettabile per Logging, sostituisci lo spazio tra la data e l'ora con la lettera T.

Ad esempio, per eseguire una ricerca nelle ultime tre ore:

timestamp >= "2016-06-27T14:40:00-04:00"

Ecco un altro esempio: per eseguire una ricerca da tre a cinque ore fa:

timestamp >= "2016-06-27T12:40:00-04:00" AND
timestamp <= "2016-06-27T14:40:00-04:00"

Riduci al minimo le ricerche globali e sottostringhe

Non cedere alla tentazione di prendere scorciatoie durante la digitazione delle query.

Esempio: non utilizzare ricerche globali

Se stai cercando una voce di log con "Hello Kitty" nel payload:

  • Non utilizzare una ricerca globale. Per un motivo, tutte vengono eseguite per ricerche di sottostringhe:

       "Hello Kitty"   -- THIS CAUSES A SLOW SEARCH!

  • Limita la ricerca a un singolo campo, anche se devi mantenere la ricerca delle sottostringhe:

       textPayload:"Hello Kitty"

  • Utilizza un test di uguaglianza se puoi:

       textPayload = "Hello Kitty"

  • Fai riferimento a singoli campi in un payload, se le tue voci di log hanno payload strutturati:

       jsonPayload.my_favorite_cat = "Hello Kitty"

  • Utilizza un campo indicizzato per limitare la ricerca:

       logName = "projects/my-project_id/logs/somelog" AND
   jsonPayload.my_favorite_cat = "Hello Kitty"

  • Utilizza la funzione SEARCH e specifica il testo completo da abbinare. La funzione SEARCH esegue una corrispondenza senza distinzione tra maiuscole e minuscole:

      SEARCH("Hello Kitty")

    Non utilizzare la funzione SEARCH e specificare testo parziale. Ad esempio, la funzione seguente non corrisponde a "Hello Kitty".

      SEARCH("Hello Kit")

Esempi di ricerca

Le voci di log visualizzate sono quelle corrispondenti a una query. Se il menu Vai a data/ora contiene un valore, il display scorre fino a quel momento. Ecco alcuni esempi di query:

resource.type=gae_app

Trova tutte le voci di log di App Engine. Per un elenco dei tipi di risorse, vedi Elenco delle risorse monitorate.

Mentre digiti, l'anteprima suggerisce i completamenti per campi come resource.type.

resource.type=gae_app AND logName:request_log

Trova le voci di log per le app App Engine dai nomi di log contenenti request_log. Tieni presente quanto segue:

  • L'operatore = è l'uguaglianza esatta. Il tipo di risorsa deve essere esattamente "gae_app", tranne che per le lettere maiuscole e minuscole.
  • L'operatore : significa "ha". Il campo logName deve contenere request_log in qualsiasi lettera maiuscola. Il nome effettivo del log è molto più lungo. L'utilizzo di : potrebbe rallentare le ricerche.
  • I due confronti sono uniti da AND. Puoi anche utilizzare OR, ma il valore AND viene usato se tralascia l'operatore.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Trova le voci di log con uno dei due tipi di risorsa: istanza VM di Compute Engine o istanza VM AWS EC2. Le voci di log devono avere severity o almeno ERROR, il che equivale alla selezione di ERROR nel menu della gravità dell'interfaccia della query.

logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"

Trova tutte le voci del log di controllo dell'attività di amministrazione nel progetto [PROJECT_ID]. Gli audit log utilizzano tutti lo stesso nome di log in un progetto, ma hanno tipi di risorse diversi. L'ID log cloudaudit.googleapis.com/activity deve avere la codifica URL nel nome log. L'uso dell'uguaglianza nel confronto velocizza la ricerca. Per ulteriori informazioni, consulta Informazioni sugli audit log.

unicorn

Trova le voci di log contenenti unicorn in qualsiasi campo e in qualsiasi lettera maiuscola. Un termine di ricerca che non fa parte di un confronto tra campi è una query "tutti i campi".

unicorn phoenix

Trova le voci di log che contengono unicorn in un campo e phoenix in un determinato campo.

textPayload:(unicorn phoenix)

Trova le voci di log il cui campo textPayload contiene sia unicorn che phoenix in qualsiasi ordine: AND è implicito tra le due parole.

textPayload:"unicorn phoenix"

Trova le voci di log il cui campo textPayload contiene la stringa "unicorn phoenix".

NOT textPayload: "unicorn phoenix"

Trova le voci di log il cui campo textPayload non contiene la stringa "unicorn phoenix". Questo tipo di query riduce le voci di log indesiderate.

timestamp >= "2016-11-29T23:00:00Z" timestamp <= "2016-11-29T23:30:00Z"

Trova le voci di log entro un periodo di 30 minuti.

Risoluzione dei problemi

Problemi di sintassi

In caso di problemi con le espressioni delle query, verifica quanto segue:

  • La query rispetta le regole di sintassi, con parentesi e virgolette corrispondenti.

  • I nomi dei campi di voce di log sono stati digitati correttamente.

  • Le operazioni booleane sono in lettere maiuscole (AND, OR, NOT).

  • Assicurati di utilizzare NULL_VALUE per rappresentare i valori null JSON.

  • Le espressioni booleane come restrizioni globali o come lato destro dei confronti devono essere racchiuse tra parentesi per maggiore chiarezza. Ad esempio, le due query riportate di seguito hanno lo stesso aspetto, ma non lo sono:

    insertId = "ABC-1" OR "ABC-2"  -- ERROR!?
insertId = ("ABC-1" OR "ABC-2")

  • Il testo senza virgolette non deve contenere caratteri speciali. In caso di dubbi, aggiungi le virgolette doppie. Ad esempio, il primo confronto riportato di seguito non è valido a causa dell'operatore di sottostringa incorporato (:). Il confronto deve essere scritto tra virgolette:

    insertId = abc:def  -- ILLEGAL!
insertId = "abc:def"

  • Google Cloud CLI richiede che la query sia racchiusa tra virgolette doppie. Per utilizzare le virgolette doppie per l'escape dei caratteri speciali con il comando gcloud logging, racchiudi l'intera query tra virgolette singole:

    gcloud logging read 'resource.type=gce_instance AND jsonPayload.message="Stopped Unattended Upgrades Shutdown."'
gcloud logging read 'timestamp>="2020-06-17T21:00:00Z"'

  • Quando applichi un filtro in base a un campo associato al tipo di messaggio Any, il campo value viene trasferito automaticamente. Pertanto, non includere value nella query.

    Ad esempio, il campo Status in un messaggio AuditLog ha un campo details di tipo google.protobuf.Any. Per eseguire una query sul campo details, ometti il campo value quando specifichi il filtro:

    • Cosa fare

      protoPayload.status.details.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"

    • Cosa non fare

      protoPayload.status.details.value.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"