Linguaggio di query di Logging

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

Per informazioni dettagliate sulla progettazione del linguaggio delle query di Logging, consulta le specifiche formali dell'API di Google per il filtro.

Per esempi di query comuni che potresti utilizzare, vedi Esempi di query con Esplora log.

Panoramica

Puoi utilizzare il linguaggio di query di Logging in Esplora log nella console Google Cloud, l'API Logging o l'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, ad esempio una cartella o un progetto Google Cloud.

Puoi creare query basate sul campo indicizzato LogEntry utilizzando gli operatori logici AND e OR. Utilizzando il campo resource.type negli esempi seguenti, la grammatica della lingua delle query di logging ha il seguente aspetto:

  • Limitazione semplice: resource.type = "gae_app"

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

  • Limitazione disgiuntiva: 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 a voci di log di Compute Engine con valori della gravità almeno ERROR e il cui campo textPayload non contiene la stringa robotal suo interno. I confronti delle stringhe non sono sensibili alle maiuscole. I nomi resource, severity e textPayload sono definiti nel tipo LogEntry.

Notazione della sintassi

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

Tieni presente quanto segue:

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

  • Il linguaggio delle query di Logging non distingue tra maiuscole e minuscole, 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 è un valore singolo o un'espressione booleana:

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

La prima riga è un esempio di confronto che è un singolo valore. Questi tipi di confronto sono limitazioni globali. Ogni campo di una voce di log viene confrontato con il valore utilizzando l'operatore has in modo implicito. Per questo esempio, se un campo in un LogEntry o il relativo payload, contiene la frase "Il gatto nel cappello", il confronto è riuscito.

La seconda riga è un esempio di confronto che è 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 racchiusa tra parentesi. Ad esempio, "gae_app". Per i valori JSON null, 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 due espressioni seguenti 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 le stesse:

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

Questa documentazione utilizza sempre AND e NOT.

Per tutti i filtri tranne quelli utilizzati dalle visualizzazioni di log, puoi utilizzare gli operatori AND, OR e NOT. Le visualizzazioni di log supportano solo 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 essere scritti con le maiuscole. Le lettere minuscole and, or e not vengono analizzate come termini di ricerca.

Confronti

I confronti hanno il formato seguente:

[FIELD_NAME] [OP] [VALUE]

Gli elementi del confronto sono descritti di seguito:

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

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

    Se il componente di un nome di 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 i dettagli, consulta gli identificatori di percorso del campo 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 scoprire come cercare le voci di log utilizzando espressioni regolari, vedi Utilizzo di espressioni regolari.

  • [VALUE]: è un numero, una stringa, una funzione o un'espressione parenthesize. Le stringhe vengono utilizzate per rappresentare testo arbitrario, oltre a valori booleani, enumerazioni e byte-string. Il valore [VALUE] viene convertito nel tipo di campo prima del confronto. Per i valori JSON null, utilizza NULL_VALUE.

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

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 ogni elemento. Ad esempio:

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

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

Identificatori di percorsi di campi

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

Ecco l'elenco corrente dei campi delle voce di log. Ciascun campo è seguito dal livello successivo di nome, se applicabile:

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status e userAgent }
  • insertId
  • jsonPayload { variabile }
  • labels { variabile }
  • 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 percorsi sul campo che puoi utilizzare nei confronti:

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

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

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

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

Quando esegui query su mappe o campi struct, devi conservare le lettere maiuscole e minuscole e la formattazione delle loro espressioni nell'espressione.

Ad esempio, jsonPayload è un campo struct, quindi il nome di un campo nidificato all'interno di jsonPayload, ad esempio 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 di buffer di protocollo protoPayload, non è necessario conservare la richiesta.

Per informazioni sui tipi di campi LogEntry, consulta il riferimento google.logging.v2.

Caratteri speciali

Se un campo LogEntry contiene caratteri speciali, il campo di log deve essere citato. 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 del campo che fanno riferimento a oggetti o array, in questo documento consulta Tipi di oggetti e array.

Tipi di risorse monitorate

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

Ad esempio, le VM di Compute Engine utilizzano il tipo di risorsa gce_instance, mentre 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 dei tipi di risorsa monitorata nei log vengono indicizzati. L'utilizzo di corrispondenze delle sottostringhe comporta tempi di query più lenti.

Campi mancanti

Se utilizzi un nome di campo in una query e questo non viene visualizzato in una voce di log, il campo è mancante, non definito o predefinito:

  • Se il campo fa parte del payload della voce di log (jsonPayload o protoPayload) o è all'interno di un'etichetta nella sezione labels della voce di log, significa che il campo è mancante. L'utilizzo di un campo mancante non mostra un errore, ma tutti i confronti che utilizzano campi mancanti vengono eseguiti senza errori.

    Esempi: jsonPayload.nearest_store, protoPayload.name.nickname

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

    Esempi: httpRequest.remoteIp, trace, operation.producer

  • In caso contrario, il campo è non definito, ovvero 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 eseguire il test per un determinato valore nel campo, utilizza il confronto :*. Ad esempio, il seguente confronto ha esito positivo se il campo operation.id è esplicitamente presente in una voce di log:

operation.id:*

Nota il comportamento delle seguenti query:

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

    -- Returns TRUE
NOT missingField=foo

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

    -- Returns FALSE
missingField!=foo

Tipi di oggetti e array

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

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

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

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

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

  • Un campo array archivia un elenco di valori, tutti dello stesso tipo. Ad esempio, un campo contenente le misurazioni potrebbe avere una matrice di numeri:

    {8.5, 9, 6}

    Quando vengono eseguiti i confronti e [FIELD_NAME] è un campo di 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 di array che archivia {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 generale risulta completato.

Valori e conversioni

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

Tipo di campo Valore della query consentito
bool

"Vero" o "falso" in qualsiasi lettera maiuscola. Esempi: "Vero", "vero"
bytes

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

Una stringa contenente un numero decimale seguito da una delle unità "ns", "us", "ms", "s", "m" o "h". La durata è precisa in nanosecondi. Esempio: "3.2s".
enum

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

Qualsiasi numero, con o senza segno e la parte esponenziale o le stringhe di valore speciali "NaN", "-Infinity" e "Infinity" (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 con codifica ASCII o 7 bit UTF-8. Le virgolette devono essere precedute dal carattere di escape con una barra rovesciata.

I valori stringa 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) o . (punto).

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

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

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

Se un tentativo di conversione non riesce, il confronto non riesce.

Quando una conversione richiede una stringa, puoi anche utilizzare un numero o testo senza virgolette, se non contengono caratteri speciali come gli spazi e gli operatori. Analogamente, quando una conversione richiede un numero, puoi utilizzare una stringa i cui contenuti sono 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 tipo intero a 64 bit, scrivi il valore come stringa, ad esempio "9223372036854775807".

Tipi di campi dei log

Come viene determinato il tipo di campo di una voce di log:

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

  • I campi di log che fanno parte di oggetti protoPayload sono anche campi buffer di protocollo e hanno tipi espliciti. Il nome del tipo di buffer di protocollo è memorizzato nel campo "@type" di protoPayload. Per ulteriori informazioni, consulta la mappatura di JSON.

    Quando filtri in base a un campo associato al tipo di messaggio Any, il campo value viene spostato automaticamente. Pertanto, non includerlo nella query. Per maggiori informazioni, consulta la pagina Risoluzione dei problemi.

  • I campi di log all'interno di jsonPayload hanno tipi dedotti dal valore del campo al momento della ricezione della voce di log:

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

    I numeri interi lunghi (64 bit) sono memorizzati nei campi delle stringhe, perché non possono essere rappresentati esattamente come i valori double.

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

Commenti

I commenti iniziano con due trattini (--) e il testo che segue i 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 per i seguenti casi:

  • Per annotare i filtri complessi con le informazioni sul funzionamento 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 del commento:

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

Operatori di confronto

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

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

L'operatore di sottostringa (:) è applicabile a string e bytes ed è gestito come se l'uguaglianza è che l'operando destro debba essere solo uguale a una parte del campo a sinistra. Le corrispondenze delle sottostringhe nei campi indicizzati non sfruttano gli indici dei log.

Limitazioni globali

Se il confronto consiste in un singolo valore, è chiamato limitazione globale. Logging utilizza l'operatore has (:) per determinare se un campo in una voce di log o se il suo payload contiene la limitazione globale. In caso affermativo, il confronto riesce.

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

"The Cat in The Hat"

Puoi combinare le limitazioni 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 segue:

(cat AND (hat OR bat))

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

Una restrizione globale consente di eseguire facilmente query sui log per un determinato valore. Ad esempio, se nel log delle tue attività cerchi voci contenenti GCE_OPERATION_DONE, puoi utilizzare la seguente query:

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

Anche se le limitazioni globali sono facili, possono essere lente. Per ulteriori informazioni, consulta la sezione Trovare rapidamente le voci di log in questo documento.

Functions

Puoi utilizzare le funzioni integrate come restrizioni globali nelle query:

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

dove argument è un valore, un nome di campo o un'espressione parenthesize. 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 [LOG_ID] cloudaudit.googleapis.com%2Factivity:

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

origine

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

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

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

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, ad esempio logName o jsonPayload.a_field. Il valore del campo determina se la voce di log è nell'esempio. 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 di voci di log con valori che [FIELD] include. È un numero maggiore di 0,0 e non superiore a 1,0. Ad esempio, se specifichi 0.01, l'esempio 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 è 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 in modo uniforme, l'esempio risultante può essere alterato. Nel peggiore dei casi, quando [FIELD] contiene sempre lo stesso valore, l'esempio risultante contiene l'elemento [FRACTION] di tutte le voci di log o nessuna voce di log.

Se in una voce di log è presente [FIELD], allora:

  • Viene calcolato un hash del valore.
  • Il valore sottoposto ad hashing, che è un numero, è diviso per il valore massimo possibile con hashing.
  • Se la frazione risultante è minore o uguale a [FRACTION], la voce di log viene inclusa nell'esempio; in caso contrario viene esclusa dal campione.

Se [FIELD] non compare in una voce di log, allora:

  • Se [FIELD] fa parte del payload della voce di log o delle sezioni labels, la voce di log non viene selezionata per l'esempio, anche se [FRACTION] è 1.
  • In caso contrario, la voce di log viene trattata come se fosse all'interno della voce di log [FIELD] e il valore di [FIELD] è 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 le voci di log con campi predefiniti dall'esempio, utilizza l'operatore field-exists, :*. La seguente query produce un campione dell'1% di voci di log che ha 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 fonte interna o esterna. Ad esempio:

ip_in_net([FIELD], [SUBNET])

[FIELD] è un campo di valori stringa nella voce di log contenente un indirizzo o un intervallo IP. Il campo può essere ripetuto, nel qual caso solo uno dei campi ripetuti deve avere un indirizzo o un intervallo contenuti nella subnet.

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

Esempio: la seguente query verifica un indirizzo IP nel payload delle voci di log del 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 manca [FIELD], il valore predefinito o non contiene un indirizzo o un intervallo di indirizzi IP legali, la funzione restituisce false. Per ulteriori informazioni sui campi mancanti e predefiniti, consulta la sezione Campi mancanti in questo documento.

Esempi di indirizzi e intervalli IP supportati sono i seguenti:

  • 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 integrata SEARCH 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 un valore letterale di stringa. Nel primo modulo viene cercata l'intera voce di log. Nel secondo modulo, devi specificare il campo nella voce di log da cercare.

Devi specificare il campo query. Se questo campo non è specificato, verrà 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 inseriti in apici. Questo comportamento è diverso da quello di BigQuery, che conserva le maiuscole/minuscole nei token inseriti negli apici. Per informazioni sulle regole dell'analizzatore sintattico, consulta il documento BigQuery Regole dell'analizzatore sintattico.

Quando crei una ricerca, tieni presente quanto segue:

  • I token non fanno distinzione tra maiuscole e minuscole. Le seguenti funzioni generano 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 sottostringhe, le funzioni precedenti non soddisfano un campo il cui valore è "tutto il mondo".

  • Se non specifichi il campo in cui cercare, la funzione SEARCH corrisponde a una voce di log quando questa voce contiene tutti i token. Tuttavia, l'ordine dei token non è importante e non è necessario che i token vengano trovati nello stesso campo della voce di log.

    Le seguenti funzioni generano 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 cerca solo in quel campo. Una corrispondenza si verifica quando quel campo contiene tutti i token, ma l'ordine dei token non è importante.

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

    SEARCH(textPayload, "hello world")

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

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

    Poiché gli apici in eccesso vengono utilizzati nelle seguenti funzioni, generano risultati diversi:

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

Il linguaggio di query di Logging supporta diversi modi per cercare nei dati di log. Quando si cerca una stringa, è più efficiente utilizzare la funzione SEARCH piuttosto che eseguire una ricerca globale o una ricerca di sottostringhe. Tuttavia, non puoi utilizzare la funzione SEARCH per creare corrispondenze con campi non di testo. Per indicazioni sull'esecuzione delle operazioni di ricerca, vedi Ridurre a icona le ricerche globali e le sottostringhe.

Ricerca per data e ora

Nell'interfaccia puoi impostare limiti specifici per la data e l'ora da mostrare nelle voci di log. 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 voci di log utilizzando le scorciatoie di timestamp. Ad esempio, puoi inserire una data con un operatore di confronto per ottenere tutte le voci di log dopo un determinato giorno:

timestamp > "2016-11-29"

Utilizzo di espressioni regolari

Puoi utilizzare espressioni regolari per creare query e creare filtri per i sink, le metriche e ovunque vengano utilizzati i filtri di log. Puoi utilizzare espressioni regolari in 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 con espressioni regolari hanno le seguenti caratteristiche:

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

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

  • Per impostazione predefinita, le query sono sensibili alle maiuscole e non sono ancorate.

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

Una query dell'espressione regolare ha la seguente struttura:

Associa uno schema:

jsonPayload.message =~ "regular expression pattern"

Non corrisponde a un pattern:

jsonPayload.message !~ "regular expression pattern"

=~ e !~ trasformano la query in una query di espressione regolare e il pattern che stai cercando di trovare deve essere racchiuso tra virgolette doppie. Per eseguire query sui pattern che contengono le virgolette, esegui l'escape utilizzando una barra rovesciata.

Esempi di query di log con 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)"
Esegui una query con gli ancoraggi logName =~ "/my%2Flog$"
Query non corrispondente a un pattern labels.pod_name !~ "foo"
Query che utilizza l'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$"

Ricerca rapida delle voci di log

Per trovare le voci di log in modo più efficiente, procedi nel seguente modo:

  • Query che utilizza i campi indicizzati.
  • Riduci al minimo il numero di voci di log da cercare.

Utilizzare i 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 in cui eseguire la ricerca.

Ottimizzare le query

Velocizza le ricerche riducendo il numero di log, il numero di voci di log o l'intervallo di tempo delle ricerche. Ancora meglio, potete ridurre tutti e tre.

Esempio: utilizza il nome di log corretto

Specifica il log contenente le voci di tuo interesse. Assicurati di conoscere il nome effettivo del log esaminando una delle voci del log. Ad esempio, l'anteprima mostra che nella sezione Compute Engine è presente un log denominato "activity". Per un'analisi più approfondita delle voci di log di controllo dell'attività di amministrazione, il log è in realtà denominato "cloudaudit.googleapis.com/activity".

Il seguente confronto è errato. Non trova corrispondenze, perché utilizza un nome di log errato:

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

Il seguente confronto è corretto. Sceglie le voci di log dalle voci di log di controllo dell'attività di amministrazione. Devi codificare l'URL con il nome del log come mostrato di seguito:

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

Esempio: scegli le voci di log corrette

Se sai che le voci di log che vuoi provengono da una determinata istanza VM, specificalo. Trova i nomi delle etichette corretti controllando 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 in formato RFC 3339 è utilizzare il comando GNU/Linux date:

$ 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 query seguenti. Per creare un timestamp accettabile per Logging, sostituisci lo spazio tra la data e l'ora con la lettera T.

Ad esempio, per cercare nelle ultime tre ore:

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

Per fare un altro esempio, da cercare tra tre e cinque ore fa:

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

Riduci a icona le ricerche globali e sottostringhe

Evita la tentazione di utilizzare delle scorciatoie durante la digitazione delle query.

Esempio: non utilizzare le ricerche globali

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

  • Non eseguire una ricerca globale. Per un motivo, sono tutte ricerche in sottostringa:

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

  • Sì limita la ricerca a un solo campo, anche se devi conservare la ricerca con sottostringa:

       textPayload:"Hello Kitty"

  • Esegui un test di uguaglianza se puoi:

       textPayload = "Hello Kitty"

  • Sì. Fai riferimento ai singoli campi di un payload, se le tue voci di log hanno payload strutturati:

       jsonPayload.my_favorite_cat = "Hello Kitty"

  • Sì. 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 corrispondente. La funzione SEARCH esegue una corrispondenza senza distinzione tra maiuscole e minuscole:

      SEARCH("Hello Kitty")

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

      SEARCH("Hello Kit")

Esempi di ricerca

Le voci di log mostrate sono quelle che corrispondono a una query. Se il menu Vai alla durata 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, consulta l'articolo Elenco delle risorse monitorate.

Mentre digiti, l'anteprima suggerisce il completamento di 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. Nota:

  • L'operatore = è esattamente un'uguaglianza. Il tipo di risorsa deve essere esattamente "gae_app", fatta eccezione per le lettere maiuscole e minuscole.
  • L'operatore : significa "has". Il campo logName deve contenere request_log, in qualsiasi lettera. Il nome effettivo del log è molto più lungo. L'uso di : potrebbe rallentare le ricerche.
  • I due confronti vengono uniti da AND. Puoi anche utilizzare OR, ma si presume AND se non specifichi l'operatore.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Trova le voci di log con uno dei due tipi di risorse: istanza VM di Compute Engine o istanza VM di AWS EC2. Le voci di log devono avere almeno severity ERROR, che equivale a selezionare ERROR nel menu della gravità dell'interfaccia 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]. Tutti gli audit log utilizzano lo stesso nome di log in un progetto, ma hanno tipi di risorse diversi. L'ID log cloudaudit.googleapis.com/activity deve essere codificato tramite URL nel nome del log. L'uso dell'uguaglianza nel confronto accelera 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. Un termine di ricerca che non fa parte di un confronto di campi è una query "tutti i campi".

unicorn phoenix

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

textPayload:(unicorn phoenix)

Trova le voci di log il cui campo textPayload contiene sia unicorn sia 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.

Risolvere i problemi

Problemi relativi alla sintassi

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

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

  • I nomi dei campi 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 JSON null.

  • Per chiarezza, le espressioni booleane come restrizioni globali o come lato destro dei confronti devono essere racchiuse tra parentesi. Ad esempio, le due query seguenti 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. Ad esempio, il primo confronto di seguito è illegale 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 tra virgolette doppie. Per utilizzare virgolette doppie per l'escape dei caratteri speciali utilizzando 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 filtri in base a un campo associato al tipo di messaggio Any, il campo value viene spostato automaticamente. Di conseguenza, 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.*"

    • Da evitare

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