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 dei filtri.
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 della 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, ad esempio un progetto o una cartella Google Cloud.
Puoi creare query basate sul campo indicizzato LogEntry utilizzando gli operatori logici AND
e OR
.
Se utilizzi il campo resource.type
negli esempi seguenti, la grammatica
del linguaggio di query di Logging ha il seguente aspetto:
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")
- In alternativa:
Espressione congiuntiva/disgiuntiva complessa:
resource.type = "gae_app" AND (severity = "ERROR" OR "error")
Di seguito è riportato un 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à pari almeno a ERROR
e il cui campo textPayload
non contiene la stringa robot
in nessun punto. I confronti di stringhe non sono sensibili alle maiuscole. I nomi resource
, severity
e textPayload
sono definiti nel tipo LogEntry.
Notazione della sintassi
Le sezioni seguenti forniscono una panoramica della sintassi del linguaggio di query di Logging e spiegano 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 di query di Logging non fa distinzione tra maiuscole e minuscole, ad eccezione delle espressioni regolari.
Riepilogo 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 costituito da un singolo valore. Questi
tipi di confronti sono restrizioni globali. Ogni campo di una voce di log viene confrontato con il valore utilizzando implicitamente l'operatore has. In questo
esempio, se qualsiasi campo in un LogEntry
, o se il suo payload contiene la frase
"Il gatto con il cappello", il confronto ha esito positivo.
La seconda riga è un esempio di confronto, ovvero un'espressione booleana nel formato [FIELD_NAME] [OP] [VALUE]
. Un confronto ha tre componenti:
[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 JSON null, utilizzaNULL_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 identiche:
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, ad eccezione di quelli utilizzati dalle visualizzazioni dei log, puoi utilizzare gli operatori AND
, OR
e NOT
. Le visualizzazioni di 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 essere maiuscole. and
, or
e not
in minuscolo vengono analizzati come termini di ricerca.
Confronti
I confronti hanno il seguente formato:
[FIELD_NAME] [OP] [VALUE]
Un confronto ha tre componenti:
[FIELD_NAME]: è l'identificatore del percorso di un campo in una voce di log. Di seguito sono riportati alcuni esempi di questi identificatori:
resource.type resource.labels.zone resource.labels.project_id insertId jsonPayload.httpRequest.protocol labels."compute.googleapis.com/resource_id"
Se un componente di un identificatore di percorso di campo contiene caratteri speciali, deve essere racchiuso tra virgolette doppie. Ad esempio,
compute.googleapis.com/resource_id
deve essere tra virgolette perché contiene una barra/
.Per maggiori dettagli, consulta la sezione Identificatori del 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 informazioni su come eseguire ricerche nelle voci di log utilizzando le espressioni regolari, consulta Utilizzo delle espressioni regolari.
- [VALUE]: è un numero, una stringa, una funzione o un'espressione tra parentesi.
Le stringhe vengono utilizzate per rappresentare testo arbitrario, oltre a valori booleani, di enumerazione
e di stringa di byte. Il valore
[VALUE]
viene convertito nel tipo di campo prima del confronto. Per i valori JSON null, utilizzaNULL_VALUE
.
Per filtrare in base a un valore JSON nullo, 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 è (o inizia) il lato sinistro di un confronto deve essere un campo definito nel tipo LogEntry
. Per dettagli sui possibili identificatori e sui relativi valori, consulta il tipo di LogEntry.
Ecco l'elenco aggiornato dei campi delle voce di log. Ogni campo è seguito dal successivo livello di nomi per quel campo, se applicabile:
httpRequest
: {cacheFillBytes
,cacheHit
,cacheLookup
,cacheValidatedWithOriginServer
,latency
,protocol
,referer
,remoteIp
,requestMethod
,requestSize
,requestUrl
,responseSize
,serverIp
,status
,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 dei percorsi dei campi che puoi utilizzare nei confronti:
resource.type: se il primo identificatore del percorso è
resource
, l'identificatore successivo deve essere un campo del tipo MonitoredResource.httpRequest.latency: se il primo identificatore del percorso è
httpRequest
, l'identificatore successivo deve essere un campo del tipo HttpRequest.labels.[KEY] Se il primo identificatore del percorso è
labels
, l'identificatore successivo,[KEY]
, deve essere una delle chiavi delle coppie chiave-valore visualizzate nel campolabels
.logName: poiché il campo
logName
è una stringa, non puoi seguirlo con un nome di campo secondario.
Quando esegui una query sui campi map o struct, devi mantenere le lettere maiuscole e minuscole delle chiavi e la formattazione 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
. Allo stesso modo, per un campo di 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 preservare le maiuscole.
Per informazioni sui tipi di campo LogEntry
, consulta il riferimento google.logging.v2.
Caratteri speciali
Se un campo LogEntry
contiene caratteri speciali, il campo del log deve essere 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, vedi 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 corrispondenze di sottostringhe, le query saranno più lente.
Campi mancanti
Se in una query utilizzi il nome di un campo e tale campo non viene visualizzato in una voce di log, significa che il campo è mancante, non definito o predefinito:
Se il campo fa parte del payload della voce di log (
jsonPayload
oprotoPayload
) o se si trova in un'etichetta nella sezionelabels
della voce di log, il campo è mancante. Se utilizzi un campo mancante, non verrà visualizzato un errore, ma tutti i confronti con campi mancanti non avranno esito positivo.Esempi:
jsonPayload.nearest_store
,protoPayload.name.nickname
Se il campo è definito nel tipo LogEntry, il campo è predefinito. 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, ovvero un errore che viene rilevato prima dell'utilizzo della query.
Esempi:
thud
,operation.thud
,textPayload.thud
Per verificare se un campo mancante o predefinito esiste 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
in un campo mancante, il risultato èTRUE
:-- Returns TRUE NOT missingField=foo
Quando utilizzi l'operatore di confronto non uguale
!=
in un campo mancante, il risultato èFALSE
:-- Returns FALSE missingField!=foo
Tipi di oggetti e array
Ogni campo di voce di log può contenere un scalare, un oggetto o un array.
Un campo scalare memorizza un singolo valore, ad esempio
174.4
o-1
. Anche unstring
è considerato uno scalare. Anche i campi che possono essere convertiti in (o da) una stringa, comeDuration
eTimestamp
, sono di tipi scalari.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
conteneva il valore precedente,jsonPayload.x.age
avrebbe il valore24
.In un campo di array viene archiviato un elenco di valori, tutti dello stesso tipo. Ad esempio, un campo contenente le 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 tramite l'operatoreOR
. Ad esempio, sejsonPayload.shoeSize
è un campo array in cui sono archiviati{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 viene valutato come riuscito.
Valori e conversioni
Il primo passaggio per valutare un confronto consiste nel convertire il valore sul lato destro nel tipo di campo voce di log. I tipi di campi 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 Tipi di buffer di protocollo scalari. La tabella seguente spiega quali valori possono essere convertiti nei tipi di campo del log:
Tipo di campo | Valore di query consentito |
---|---|
bool |
"True" o "false" in lettere maiuscole e minuscole. Esempi: "True", "true" |
bytes |
Una stringa contenente una 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 ai nanosecondi. Esempio: "3.2 s". |
enum |
Il nome di un valore letterale di tipo 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 lettere maiuscole o meno). Esempi: "-3.2e-8", "nan". |
intNN |
Qualsiasi numero intero firmato che non superi la dimensione del tipo. Esempio: "-3". |
string |
Qualsiasi stringa contenente testo con codifica UTF-8 o ASCII a 7 bit. Le virgolette incorporate devono essere precedute dal carattere di escape con una barra rovesciata. I valori stringa devono essere racchiusi tra virgolette doppie per evitare i seguenti caratteri speciali:
|
Timestamp |
Una stringa in formato RFC 3339 o ISO 8601.
Esempi: "2014-10-02T15:01:23.045Z" (RFC 3339),
"2014-10-02" (ISO 8601). Nelle espressioni di query, i timestamp nel formato RFC 3339 possono specificare un fuso orario preceduto da "Z" o |
uintNN |
Qualsiasi numero intero senza segno che non superi la dimensione 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 anche utilizzare un numero o un testo senza virgolette se non contengono 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 tipo di numero intero a 64 bit, devi scrivere il valore come una stringa, ad esempio "9223372036854775807".
Tipi di campi dei log
Ecco come viene determinato il tipo di un 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"
diprotoPayload
. Per ulteriori informazioni, consulta la mappatura JSON.Quando filtri in base a un campo associato al tipo di messaggio
Any
, il campovalue
viene attraversato automaticamente. Pertanto, non includerlo nella query. Per maggiori informazioni, consulta la sezione Risoluzione dei problemi.I campi di log all'interno di
jsonPayload
hanno tipi che vengono dedotti dal valore del campo quando viene ricevuta la voce di log:- I campi i cui valori sono numeri non tra virgolette hanno il tipo
double
. - I campi con valori
true
ofalse
hanno il tipobool
. - I campi con valori sono stringhe di tipo
string
.
I numeri interi lunghi (64 bit) vengono memorizzati in campi stringa perché non possono essere rappresentati esattamente come valori
double
.- I campi i cui valori sono numeri non tra virgolette hanno il tipo
I tipi
Duration
eTimestamp
sono riconosciuti solo nei campi del buffer di protocollo. Altrove, questi valori sono memorizzati in campi stringa.
Commenti
I commenti iniziano con due trattini (--
) e l'eventuale testo che li segue 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 tuoi 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 normale significato in termini di numeri.
bool
: Uguaglianza indica lo stesso valore booleano. La disuguaglianza è definita datrue
>false
.enum
: 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. La disuguaglianza si basa sulla durata della durata. Esempio: come durate,"1s"
>"999ms"
.Timestamp
: uguaglianza significa lo stesso istante nel tempo. Se a e b sono valoriTimestamp
, a < b significa che a è anteriore nel tempo rispetto a b.bytes
: gli operanti vengono confrontati byte per byte, da sinistra a destra.string
: i confronti ignorano le maiuscole e le minuscole. Nello specifico, entrambi gli operandi vengono prima normalizzati tramite la normalizzazione Unicode NFKC_CF e quindi utilizzano i confronti lessicografici. Tuttavia, le ricerche basate su 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 uguaglianza, tranne per il fatto che l'operando di destra deve corrispondere solo a una parte del campo a sinistra. Le corrispondenze di sottostringhe nei campi indicizzati
non sfruttano gli indici di log.
Limitazioni globali
Se il confronto è costituito da un singolo valore, viene chiamato restrizione globale. Logging utilizza l'operatore has (:
) per determinare
se eventuali campi di una voce di log o il relativo payload contengono la restrizione globale.
In caso affermativo, il confronto viene eseguito correttamente.
La query più semplice scritta in termini di restrizione 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 che contiene cat
e un campo che contiene hat
o bat
, scrivi la query come:
("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 è un modo per eseguire query nei log per un determinato valore.
Ad esempio, se nel log delle attività cerchi voci contenenti una 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"
Anziché utilizzare restrizioni globali, che possono essere lente, ti consigliamo di utilizzare la funzione SEARCH
integrata e di eseguire query sui campi indicizzati. Per ulteriori informazioni, consulta Trovare rapidamente le voci di log in questo documento.
Funzioni
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 parentesi 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 dal 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")
trasmetti
La funzione cast
accetta due parametri: il campo LogEntry da trasmettere e il tipo di dati in cui il campo viene convertito in:
cast([FIELD], [TYPE][, OPTION])
I parametri dell'espressione precedente sono definiti come segue:
[FIELD]
: il nome di un campo nella voce di log, ad esempiologName
ojsonPayload.a_field
.[TYPE]
: il tipo di dati, ad esempioSTRING
,INT64
,FLOAT64
,BOOL
.TIMESTAMP
oDURATION
: alcuni tipi di dati offrono opzioni aggiuntive, ad esempio la specifica di un fuso orario del database del fuso orario IANA per il tipo di datiTIMESTAMP
.
Ad esempio, la seguente query trasmette il campo timestamp
in una 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, ad esempiologName
ojsonPayload.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 restituiscono un errore.
Puoi concatenare le funzioni cast
e regexp_extract
:
CAST(REGEXP_EXTRACT(CAST(timestamp, STRING), "\\d+:\\d+:\\d+\\.(\\d+)"), INT64) < 500
Nell'esempio precedente, il campo timestamp
viene trasmesso 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.
source
La funzione source
associa le voci di log di una determinata risorsa nella gerarchia delle organizzazioni, delle cartelle e dei progetti Google Cloud.
La funzione source
non corrisponde alle risorse figlio. Ad esempio, se utilizzi source(folders/folder_123)
, vengono trovati i log della risorsa folder_123
e non i log delle risorse del progetto Google Cloud all'interno di folder_123
.
Per eseguire 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, ad esempio 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 che [FIELD]
deve includere. Deve essere 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:
viene utilizzato un algoritmo deterministico, basato sull'hashing, 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 uniformemente, il campione risultante può essere disallineato.
Nel peggiore dei casi, quando [FIELD]
contiene sempre lo stesso valore, l'esempio risultante contiene la [FRACTION]
di tutte le voci di log o nessuna voce di log.
Se [FIELD]
compare in una voce di log, allora:
- Viene calcolato un hash del valore.
- Il valore hash, ovvero un numero, viene diviso per il massimo valore hash possibile.
- Se la frazione risultante è inferiore o uguale a
[FRACTION]
, la voce di log è inclusa nel campione, altrimenti 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 sezionilabels
, 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]
fosse nella voce di log e il valore di[FIELD]
è il valore predefinito. Il valore predefinito è determinato dal tipo LogEntry. Per ulteriori informazioni sui campi mancanti e predefiniti, consulta Campi mancanti in questo documento.
Per escludere dall'esempio 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. Potresti 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 avere un indirizzo o un intervallo contenuto nella subnet.
[SUBNET]
è una costante stringa per un indirizzo o un intervallo IP. Se [SUBNET]
non è un indirizzo o un intervallo IP legale, viene considerato un errore, 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, [FIELD]
manca, è 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 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 eseguita la ricerca
dell'intera voce di log. Nel secondo modulo devi specificare il campo della voce di log da cercare.
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 uno strumento di analisi di testo che suddivide la stringa in token. Cloud Logging esegue sempre confronti senza distinzione tra maiuscole e minuscole, anche per i token con apici inversi. Questo comportamento è diverso da quello di BigQuery,
che conserva le maiuscole nei token con apici inversi.
Per informazioni sulle regole dello strumento di analisi, consulta il documento di BigQuery sulle regole dello strumento di analisi del 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 "mondo". 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 in cui eseguire la ricerca, la funzione
SEARCH
corrisponde a una voce di log quando questa contiene tutti i token. Tuttavia, l'ordine dei token non è importante e non è necessario che si trovino 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
cerca 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 senza distinzione tra maiuscole e minuscole a una frase, racchiudila 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 seguenti funzioni, producono risultati diversi:
SEARCH("`hello world`") SEARCH("`world hello`")
Il linguaggio di query di Logging supporta diversi modi in cui puoi eseguire ricerche nei dati di log. Per cercare 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 trovare una corrispondenza con i campi non di testo.
Per indicazioni sull'esecuzione di operazioni di ricerca, consulta Ridurre al minimo le ricerche globali e di sottostringhe.
Ricerca per data/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 in precedenza.
Puoi cercare le voci di log anche 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 delle espressioni regolari
Puoi utilizzare espressioni regolari per creare query e filtri per sink, metriche e ovunque vengono utilizzati i filtri di log. Ad esempio, 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 basate su espressioni regolari hanno le seguenti caratteristiche:
Solo i campi del tipo di stringa possono essere abbinati a un'espressione regolare.
La normalizzazione delle stringhe non viene eseguita; ad esempio,
kubernetes
non viene considerato comeKUBERNETES
. Per ulteriori informazioni, consulta la sezione Operatori di confronto.Le query sono sensibili alle maiuscole e non sono ancorate per impostazione predefinita.
Puoi utilizzare gli operatori booleani tra più espressioni regolari sul lato destro dell'operatore di confronto delle espressioni regolari
=~
e!~
.
Una query di espressione regolare ha la seguente struttura:
Associa un pattern:
jsonPayload.message =~ "regular expression pattern"
Non corrisponde a un pattern:
jsonPayload.message !~ "regular expression pattern"
I valori =~
e !~
modificano la query in una query basata su espressione regolare e il pattern per cui cerchi di trovare una corrispondenza deve essere racchiuso tra virgolette doppie. Per eseguire query su pattern che contengono virgolette doppie, esegui il escape utilizzando una barra rovesciata.
Esempi di query sui log con le 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 utilizzando un valore booleano or |
labels.pod_name =~ "(foo|bar)" |
Esegui 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 efficiente, segui questi passaggi:
- Query utilizzando campi indicizzati.
- Riduci al minimo il numero di voci di log in cui eseguire la ricerca.
Utilizza campi indicizzati
Logging indicizza sempre i seguenti campi LogEntry:
- resource.type
- resource.labels.*
- logName
- gravità
- timestamp
- insertId
- operation.id
- trace
- httpRequest.status
- etichette.*
- split.uid
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.
Ottimizza le query
Velocizza le ricerche riducendo il numero di log, il numero di voci di log o l'intervallo di tempo delle ricerche. Inoltre, puoi ridurli tutti e tre.
Esempio: utilizzare il nome log corretto
Specifica il log contenente le voci di log che ti interessano. Assicurati di conoscere il nome effettivo del log esaminando una delle voci di log. Ad esempio, l'anteprima mostra che la sezione Compute Engine contiene un log denominato "activity". Dopo un'analisi più approfondita delle voci degli audit log per le attività di amministrazione, il nome del log è "cloudaudit.googleapis.com/activity".
Il seguente confronto non è corretto. Non corrisponde ad alcun dato perché utilizza il nome di log errato:
logName = "projects/my-project-id/logs/activity" -- WRONG!
Il seguente confronto è corretto. Sceglie le voci di log dalle voci di audit log dell'attività di amministrazione. Devi eseguire la codifica URL del nome del log, come mostrato 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, specificala. Verifica che i nomi delle etichette siano corretti ispezionando 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 timestamp utili nel formato RFC 3339 consiste nell'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 eseguire una ricerca nelle ultime tre ore:
timestamp >= "2016-06-27T14:40:00-04:00"
Come ulteriore esempio, per effettuare 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 di sottostringhe
Evita la 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, si tratta tutte di ricerche di sottostringhe:
"Hello Kitty" -- THIS CAUSES A SLOW SEARCH!
Limita la ricerca a un singolo campo, anche se devi mantenere la ricerca di sottostringhe:
textPayload:"Hello Kitty"
Esegui un test di uguaglianza se puoi:
textPayload = "Hello Kitty"
Fai riferimento ai singoli campi in un payload, se le 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 funzioneSEARCH
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 visualizzate sono quelle che corrispondono a una query. Se il menu Vai all'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 i campi come
resource.type
.resource.type=gae_app AND logName:request_log
Trova le voci di log per le app App Engine dai nomi dei log contenenti
request_log
. Tieni presente quanto segue:- L'operatore
=
rappresenta l'uguaglianza esatta. Il tipo di risorsa deve essere esattamente"gae_app"
, ad eccezione dell'uso di lettere maiuscole e minuscole. - L'operatore
:
significa "ha". Il campologName
deve contenererequest_log
, in qualsiasi lettera maiuscola. Il nome effettivo del log è molto più lungo. L'uso di:
potrebbe comportare un rallentamento delle ricerche. - I due confronti sono uniti da
AND
. Puoi anche utilizzareOR
, maAND
si presume se tralascia l'operatore.
- 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
di almenoERROR
, il che equivale a selezionare ERRORE nel menu della gravità dell'interfaccia della query.logName = "projects/[PROJECT_ID]/logs/cloudaudit.googleapis.com%2Factivity"
Trova tutte le voci di audit log 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 logcloudaudit.googleapis.com/activity
deve essere codificato come URL nel nome log. L'utilizzo 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 con 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 ephoenix
in un campo.textPayload:(unicorn phoenix)
Trova le voci di log il cui campo
textPayload
contiene siaunicorn
siaphoenix
in qualsiasi ordine: il valoreAND
è 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
Se hai problemi con le espressioni delle query, controlla quanto segue:
La query rispetta le regole di sintassi, con parentesi e virgolette corrispondenti.
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 tra parentesi. Ad esempio, le due query seguenti hanno lo stesso aspetto, ma non sono:
insertId = "ABC-1" OR "ABC-2" -- ERROR!? insertId = ("ABC-1" OR "ABC-2")
Il testo 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'interpretazione letterale di caratteri speciali con il comando
gcloud logging
, racchiudi l'intera query tra apici 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 a un campo associato al tipo di messaggio
Any
, il campovalue
viene attraversato automaticamente. Pertanto, non includerevalue
nella query.Ad esempio, il campo
Status
in un messaggio AuditLog ha un campodetails
di tipogoogle.protobuf.Any
. Per eseguire una query sul campodetails
, ometti il campovalue
quando specifichi il filtro:Cosa fare
protoPayload.status.details.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"
Azione sconsigliata
protoPayload.status.details.value.conditionNotMet.userVisibleMessage =~ "Specified reservation.*"