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 Google per i filtri.

Per esempi di query comuni che potresti utilizzare, consulta Query di esempio con 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, ad esempio un progetto o una cartella Google Cloud.

Puoi creare query in base al LogEntry campo indicizzato utilizzando gli operatori logici AND e OR. Utilizzando il campo resource.type negli esempi seguenti, la grammatica del linguaggio di query di logging ha il seguente aspetto:

  • Limitazione semplice: resource.type = "k8s_cluster"

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

  • Limitazione disgiuntiva: resource.type = "k8s_cluster" OR resource.type = "gce_instance"

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

  • Espressione congiuntiva/disgiuntiva complessa: resource.type = "k8s_cluster" 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 abbina le voci di log di Compute Engine con valori di gravità almeno ERROR e il cui campo textPayload non contiene la stringa robot. I confronti delle 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 delle 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 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 è un singolo valore o un'espressione booleana:

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

La prima riga è un esempio di confronto che è un singolo valore. Questi tipi di confronti sono limitazioni globali. Ogni campo di una voce di log viene confrontato con il valore utilizzando implicitamente l'operatore has. Ad 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 del tipo [FIELD_NAME] [OP] [VALUE]. Un confronto è composto da 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, "k8s_cluster". 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 quest'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 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 dei 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 in maiuscolo. and, or e not in minuscolo vengono analizzati come termini di ricerca.

Confronti

I confronti hanno la seguente forma:

[FIELD_NAME] [OP] [VALUE]

Un confronto è composto da tre componenti:

  • [FIELD_NAME]: è l'identificatore del percorso del campo 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 del percorso del campo contiene caratteri speciali, deve essere racchiuso tra virgolette doppie. Ad esempio, compute.googleapis.com/resource_id deve essere racchiuso tra virgolette doppie perché contiene una barra /.

    Per maggiori dettagli, consulta gli 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 scoprire come cercare le voci di log utilizzando le espressioni regolari, consulta Utilizzo delle espressioni regolari.

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

Per filtrare in base a un valore null JSON, 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 tra parentesi di confronti, 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 verifica che il campo cat abbia il valore "pelolungo" o "pelocorto". Il secondo verifica che il valore del campo animal contenga entrambe le parole "bello" e "animale domestico", in qualsiasi ordine.

Identificatori del percorso del campo

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 informazioni dettagliate sui possibili identificatori e sui relativi valori, consulta il tipo LogEntry.

Ecco l'elenco attuale dei campi di 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, 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 dei campi che puoi utilizzare nei confronti:

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

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

  • labels.[KEY] Se il primo identificatore di 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 seguirlo con nomi di campi secondari.

Quando esegui query sui campi map o struct, devi mantenere la maiuscola e la formattazione delle chiavi nell'espressione.

Ad esempio, jsonPayload è un campo struct, pertanto 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 dell'etichetta labels.env_name è diversa da labels.envName. Al contrario, quando effettui query sul campo del buffer del protocollo normale protoPayload, non è necessario mantenere le maiuscole.

Per informazioni sui tipi di campi LogEntry, consulta la documentazione di riferimento di 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 di identificatori di percorsi dei campi che fanno riferimento a oggetti o آرایه, consulta la sezione Tipi di oggetti e آرایه 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 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. L'utilizzo di corrispondenze di sottostringhe per questi valori comporta query più lente.

Campi mancanti

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

  • Se il campo fa parte del payload della voce di log (jsonPayload o protoPayload) o se si trova in un'etichetta nella sezione labels della voce di log, il campo è mancante. L'utilizzo di un campo mancante non mostrerà un errore, ma tutti i confronti che utilizzano campi mancanti non andranno a buon fine in silenzio.

    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, un errore rilevato prima dell'utilizzo della query.

    Esempi: thud, operation.thud, textPayload.thud

Per verificare se esiste un campo mancante o predefinito senza verificare la presenza di 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 del log:

operation.id:*

Tieni presente 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 della voce di log può contenere un valore scalare, oggetto o array.

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

  • Un tipo di oggetto memorizza 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 contiene il valore precedente, jsonPayload.x.age avrà il valore 24.

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

    {8.5, 9, 6}

    Quando vengono eseguiti i confronti e [FIELD_NAME] è un campo array, ogni elemento 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

    è equivalente 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 del lato destro nel tipo del campo della voce di log. I tipi di campi scalari sono consentiti nei confronti, insieme ad altri due tipi 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 tabella seguente illustra i valori che possono essere convertiti nei tipi di campi di log:

Tipo di campo Valore di query consentito
bool

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

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

Una stringa contenente un numero decimale con segno seguito da una delle unità "ns", "us", "ms", "s", "m" o "h". Le durate sono precise al nanosecondo. Esempio: "3,2 s".
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 di esponente, oppure le stringhe di valore speciale "NaN", "-Infinity" ed "Infinity" (in maiuscolo o meno). Esempi: "-3.2e-8", "nan".
intNN

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

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

I valori di stringa devono essere racchiusi tra virgolette doppie per dare un'interpretazione letterale ai seguenti caratteri speciali:

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

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

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

Una stringa nel formato RFC 3339 o ISO 8601. Esempi&colon; "2024-08-02T15&colon;01&colon;23.045Z" (RFC 3339), "2024-08-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 di nanosecondi.
uintNN

Qualsiasi numero intero non firmato 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 di numeri interi di varie dimensioni, ad esempio int32 e uint64. Quando scrivi un valore da convertire in un tipo di numero intero a 64 bit, scrivi il valore come stringa, ad esempio "9223372036854775807".

Tipi di campi di log

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

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

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

    Quando applichi un filtro a un campo associato al Any tipo di messaggio, il campo value viene attraversato automaticamente. Pertanto, non includerla 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 hanno il tipo double.
    • I campi i cui valori sono true o false sono di tipo bool.
    • I campi i cui valori sono stringhe sono di tipo string.

    Gli interi lunghi (64 bit) vengono memorizzati in campi di stringhe perché non possono essere rappresentati esattamente come valori double.

  • I tipi Duration e Timestamp sono riconosciuti solo nei campi di buffer di protocollo. In altri casi, questi valori vengono memorizzati in campi di stringa.

Commenti

I commenti iniziano con due trattini (--) e qualsiasi 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.

Potresti utilizzare i commenti nei seguenti casi:

  • Per annotare i filtri complessi con 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 attivare o disattivare 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: l'uguaglianza e la disuguaglianza hanno il loro significato normale 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. L'inequità utilizza i valori numerici sottostanti dei letterali di enumerazione.
  • Duration: l'uguaglianza indica la stessa durata. L'iniquità si basa sulla durata. Esempio: come durate, "1s">"999ms".
  • Timestamp: l'uguaglianza indica lo stesso istante di tempo. Se a e b sono valori Timestamp, a < b significa che a è precedente a b.
  • bytes: gli operandi vengono confrontati byte per byte, da sinistra a destra.
  • string: i confronti ignorano le maiuscole. Nello specifico, entrambi gli operandi vengono prima normalizzati utilizzando la normalizzazione Unicode NFKC_CF e poi vengono utilizzati i confronti lessicografici. Tuttavia, le ricerche tramite espressioni regolari non sono normalizzate. Per ulteriori informazioni sulla ricerca delle voci di log utilizzando espressioni regolari, consulta Utilizzare le espressioni regolari.

L'operatore di sottostringa (:) è applicabile a string e bytes e viene gestito come l'uguaglianza, tranne per il fatto che l'operando destro deve essere uguale solo a una parte del campo a sinistra. Le corrispondenze di sottostringhe nei campi indicizzati non sfruttano gli indici dei log.

Limitazioni globali

Se il confronto è costituito da un singolo valore, si parla di limitazione globale. La registrazione utilizza l'operatore has (:) per determinare se un campo in una voce di log o il relativo payload contiene la limitazione globale. In caso contrario, il confronto va a buon fine.

La query più semplice scritta in termini di una 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 che hanno 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 restrizioni globali: cat, hat e bat. Queste limitazioni globali vengono applicate separatamente e i risultati vengono combinati, come se l'espressione fosse stata scritta senza parentesi.

Una limitazione globale è un modo per eseguire query sui log in base a un determinato valore. Ad esempio, se nel log delle attività stai cercando voci contenenti riferimenti a 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 le limitazioni globali, che possono essere lente, ti consigliamo di utilizzare la funzione SEARCH integrata e di eseguire query sui campi indicizzati. Per ulteriori informazioni, consulta la sezione Trovare rapidamente le voci di log in questo documento.

Funzioni

Puoi utilizzare le funzioni incorporate come limitazioni globali nelle query:

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

dove argument è un valore, un nome 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] fornito dal 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 eseguire il casting e il tipo di dati in cui il campo viene convertito:

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

I parametri dell'espressione precedente sono definiti come segue:

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

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

    • TIMESTAMP o DURATION: alcuni tipi di dati offrono opzioni aggiuntive, ad esempio la possibilità di specificare un fuso orario del database dei fusi orari IANA per il tipo di dati TIMESTAMP.

Ad esempio, la seguente query esegue il casting del campo timestamp in una STRINGA 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 esempio logName o jsonPayload.a_field.
  • [REGULAR_EXPRESSION]: l'espressione regolare RE2 che deve contenere un gruppo di cattura ((...)). Deve essere utilizzato un gruppo senza cattura (?:...) se è necessario un raggruppamento aggiuntivo per l'espressione regolare. Più gruppi di cattura o nessun gruppo di cattura 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 esegue il casting del 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 millisecondo è inferiore a 500.

origine

La funzione source abbina 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 secondarie. Ad esempio, l'utilizzo di source(folders/folder_123) corrisponde ai log della risorsa folder_123 e non ai 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 un valore stringa o numerico. L'impostazione di [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 che hanno valori per [FIELD] da includere. Deve essere 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 del log che hanno valori per [FIELD]. Se [FRACTION] è 1, vengono scelte tutte le voci del log che hanno valori per [FIELD].

Esempio: la seguente query restituisce il 25% delle voci di log del 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 sottomessi ad hashing. Se i valori sottoposti ad hashing non sono distribuiti in modo uniforme, il campione risultante può essere distorto. Nel peggiore dei casi, quando [FIELD] contiene sempre lo stesso valore, il campione risultante contiene il [FRACTION] di tutte le voci di log o nessuna voce di log.

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

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

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

  • Se [FIELD] fa parte del payload o delle sezioni labels della voce di log, la voce di log non è selezionata per il sample, anche se [FRACTION] è 1.
  • In caso contrario, la voce di log viene trattata come se [FIELD] fosse presente 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 Campi mancanti in questo documento.

Per escludere dal campione le voci di log con campi predefiniti, utilizza l'operatore esiste-campo, :*. La seguente query genera un campione dell'1% delle 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 un'origine interna o esterna. Ad esempio:

ip_in_net([FIELD], [SUBNET])

[FIELD] è un campo con valore stringa nella voce di log che contiene un indirizzo IP o un intervallo. Il campo può essere ripetuto, nel qual caso solo uno dei campi ripetuti deve avere un indirizzo o un intervallo contenuto nella sottorete.

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

Esempio: la seguente query testa 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] non è presente, è predefinito o non contiene un indirizzo o un intervallo IP valido, 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
  • CIDR IPv6: 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 dei log:

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

Entrambe le forme della funzione SEARCH contengono un argomento query, che deve essere formattato come stringa letterale. Nella prima forma, viene eseguita la ricerca nell'intera voce di log. Nella seconda forma, specifichi il campo nella voce di log da cercare.

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

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

Quando crei una ricerca, tieni presente 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 è "in tutto il mondo".

  • Se non specifichi il campo da cercare, 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 che contiene i token "ciao" e "mondo":

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

  • Se specifichi il campo da cercare, la funzione SEARCH esaminerà solo quel campo. Si verifica una corrispondenza quando il campo contiene tutti i token, ma l'ordine dei token non ha importanza.

    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, ma senza distinzione tra maiuscole e minuscole, su una frase, chiuderla tra barre graffe. Ad esempio, le seguenti funzioni corrispondono alla stringa "hello world":

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

    Poiché le barre graffe vengono utilizzate nelle seguenti funzioni, producono risultati diversi:

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

Il linguaggio delle query di Logging supporta diversi modi per eseguire ricerche tra i dati dei log. Quando cerchi una stringa, è più efficiente utilizzare la funzioneSEARCH rispetto a eseguire una ricerca globale o una ricerca di sottostringa. Tuttavia, non puoi utilizzare la funzione SEARCH per trovare corrispondenze in campi diversi dal testo. Per indicazioni su come eseguire operazioni di ricerca, vedi Minimizzare le ricerche globali e con sottostringa.

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, il riquadro dei risultati 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 >= "2023-11-29T23:00:00Z"
timestamp <= "2023-11-29T23:30:00Z"

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

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

timestamp > "2023-11-29"

Utilizzo delle espressioni regolari

Puoi utilizzare le espressioni regolari per creare query e filtri per canali, metriche e ovunque vengano utilizzati i filtri dei log. Ad esempio, puoi utilizzare le espressioni regolari in Esplora log e con Google Cloud CLI.

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

Le query con 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 è 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 espressioni regolari ha la seguente struttura:

Trova una corrispondenza con 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 espressioni regolari e lo schema che stai cercando di associare deve essere racchiuso tra virgolette doppie. Per eseguire query su pattern che contengono virgolette doppie, inserisci un carattere di escape con una barra.

Esempi di query sui log utilizzando espressioni regolari

Tipo di query Esempio
Query standard sourceLocation.file =~ "foo"
Esegui una query con ricerca senza distinzione tra maiuscole e minuscole labels.subnetwork_name =~ "(?i)foo"
Query contenente virgolette jsonPayload.message =~ "field1=\"bar.*\""
Esegui una query utilizzando un valore booleano or labels.pod_name =~ "(foo|bar)"
Esegui query utilizzando le ancore logName =~ "/my%2Flog$"
Query che non corrisponde a un pattern labels.pod_name !~ "foo"
Esegui una query utilizzando 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$"

Trovare rapidamente le voci del log

Per trovare le voci di log in modo efficiente:

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

Utilizzare i campi indicizzati

La registrazione indicizza sempre i seguenti campi LogEntry:

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

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

Ottimizzare le query

Per velocizzare le ricerche, riduci il numero di log, il numero di voci di log o l'intervallo di tempo delle ricerche. Ancora meglio, puoi ridurli tutti.

Esempio: utilizza il nome del log corretto

Specifica il log contenente le voci di log che ti interessano. Assicurati di conoscere il nome effettivo del log controllando una delle voci del log. Ad esempio, il riquadro dei risultati mostra che la sezione Compute Engine contiene un log denominato "activity". Da un'analisi più approfondita delle voci dell'audit log delle attività di amministrazione, il log è in realtà denominato "cloudaudit.googleapis.com/activity".

Il seguente confronto è errato. Non corrisponde a nulla perché utilizza il nome del log errato:

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

Il seguente confronto è corretto. Scegliere le voci dei log dalle voci degli audit log delle attività di amministrazione. Devi codificare l'URL del nome del log, come mostrato di seguito:

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

Esempio: scegli le voci di log giuste

Se sai che le voci di log che ti interessano provengono da una determinata istanza VM, specificala. Controlla i nomi delle etichette corretti esaminando una delle voci di log che vuoi cercare. Nel seguente esempio, 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 in formato RFC 3339 è utilizzare il comando date di GNU/Linux:

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

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

Ad esempio, per cercare tra le ultime tre ore:

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

Ecco un altro esempio: per eseguire ricerche tra tre e cinque ore fa:

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

Riduci al minimo le ricerche globali e con sottostringhe

Evita la tentazione di usare 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, sono tutte ricerche di sottostringhe:

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

  • Non limitare la ricerca a un singolo campo, anche se devi mantenere la ricerca di sottostringhe:

       textPayload:"Hello Kitty"

  • Utilizza un test di uguaglianza se puoi:

       textPayload = "Hello Kitty"

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

       jsonPayload.my_favorite_cat = "Hello Kitty"

  • Non utilizzare un campo indicizzato per limitare la ricerca:

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

  • Non utilizzare la funzione SEARCH e specificare il testo completo da associare. La funzione SEARCH esegue una corrispondenza senza distinzione tra maiuscole e minuscole:

      SEARCH("Hello Kitty")

    Non utilizzare la funzione SEARCH e specificare un 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 corrispondenti a una query. Se il menu Vai al momento contiene un valore, il display scorre fino a quel momento. Ecco alcuni esempi di query:

resource.type=k8s_cluster

Trova tutte le voci di log di Google Kubernetes Engine. Per un elenco dei tipi di risorse, consulta Elenco delle risorse monitorate.

Mentre digiti, il riquadro delle query suggerisce i completamenti per i campi come resource.type.

resource.type=k8s_cluster AND logName:request_log

Trova le voci di log per i cluster Google Kubernetes Engine dai nomi dei log contenenti request_log. Tieni presente quanto segue:

  • L'operatore = è uguale a. Il tipo di risorsa deve essere esattamente "k8s_cluster", tranne per le lettere maiuscole.
  • L'operatore : significa "ha". Il campo logName deve contenererequest_log, in qualsiasi maiuscolo. Il nome effettivo del log è molto più lungo. L'utilizzo di : potrebbe comportare ricerche più lente.
  • I due confronti sono uniti da AND. Puoi anche utilizzare OR, ma se non inserisci l'operatore viene assunto AND.
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 Compute Engine o istanza VM AWS EC2. Le voci di log devono avere un valore severity di almeno ERROR, il che equivale a selezionare ERRORE nel menu della gravità dell'interfaccia di query.

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

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

unicorn

Trova le voci di log contenenti unicorn in qualsiasi campo, indipendentemente dalle maiuscole. 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 altro.

textPayload:(unicorn phoenix)

Trova le voci di log il cui campo textPayload contiene sia unicorn sia phoenix in qualsiasi ordine. Il carattere 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 >= "2023-11-29T23:00:00Z" timestamp <= "2023-11-29T23:30:00Z"

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

Risoluzione dei problemi

Problemi di sintassi

Se riscontri problemi con le espressioni delle query, controlla quanto segue:

  • La query obbedisce alle regole di sintassi, con parentesi e virgolette abbinate.

  • I nomi dei campi voce di log sono scritti 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 limitazioni globali o come lato destro dei confronti devono essere racchiuse tra parentesi per chiarezza. Ad esempio, le seguenti due query sembrano uguali, ma non lo sono:

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

  • Il testo non tra virgolette non deve contenere caratteri speciali. In caso di dubbi, aggiungi virgolette doppie. Ad esempio, nel seguente, il primo confronto è 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 le virgolette doppie per l'interpretazione letterale dei caratteri speciali con il comando gcloud logging, racchiudere 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 a un campo associato al Any tipo di messaggio, il campo value viene attraversato 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 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.*"