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 delle API di Google per l'applicazione dei filtri.

Per esempi di query comuni che potrebbe essere utile, vedi Esempi di query con Esplora log.

Panoramica

Puoi utilizzare il linguaggio di query di Logging in Esplora log nel nella console Google Cloud, API Logging, o il 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 Google Cloud o cartella.

Puoi creare query basate su LogEntry campo indicizzato utilizzando gli operatori logici AND e OR. Utilizzando il campo resource.type nei seguenti esempi, il valore La grammatica del linguaggio di query di Logging ha il seguente aspetto:

  • Restrizione semplice: resource.type = "k8s_cluster"

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

  • Limitazione digiuntiva: 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 corrisponde alle voci di log di Compute Engine con valori di gravità di almeno ERROR e il cui campo textPayload non contiene la stringa robot in qualsiasi punto al suo interno. I confronti di stringhe non sono sensibili alle maiuscole. I nomi resource, severity e textPayload sono definiti in Tipo di LogEntry.

Notazione della sintassi

Le sezioni seguenti forniscono una panoramica del linguaggio di query di Logging e discutere in dettaglio di come sono strutturate le query e il modo in cui viene in esecuzione. Alcuni esempi utilizzano i commenti per fornire spiegazioni testo.

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 = "k8s_cluster"

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 rispetto al valore mediante l'uso implicito dell'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, ovvero un'espressione booleana di il modulo [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 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 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, 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, ad eccezione di quelli utilizzati dalle visualizzazioni dei log, puoi utilizzare gli operatori AND, OR e NOT. Le visualizzazioni log supportano solo AND e NOT operazioni.

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

Gli operatori booleani devono sempre essere maiuscole. and minuscolo, or, e not 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 dell'identificatore di percorso di un campo contiene caratteri speciali, le virgolette doppie. Ad esempio, compute.googleapis.com/resource_id deve essere racchiuso tra virgolette doppie perché contiene una barra /.

    Per maggiori dettagli, vedi 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 scoprire 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 sono utilizzate per rappresentare un testo arbitrario, più valori booleani, enumerazioni, e byte-stringa. Il valore [VALUE] viene convertito nel tipo di campo precedente al confronto. Per i valori JSON null, 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 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 verifica che il campo cat abbia il valore "longhair" o "a pelo corto". Il secondo verifica che il valore del campo animal contenga entrambe le parole "bello" e "pet" in qualsiasi ordine.

Identificatori dei percorsi dei campi

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

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

  • httpRequest: { cacheFillBytes, cacheHit, cacheLookup, cacheValidatedWithOriginServer, latency, protocol, referer, remoteIp, requestMethod, requestSize, requestUrl, responseSize, serverIp, status, userAgent }
  • insertId
  • jsonPayload { variabile }
  • labels { variable }
  • logName
  • metadata { systemLabels, userLabels }
  • operation{ id, producer, first, last }
  • protoPayload { @type, variable }
  • 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, l'identificatore successivo deve essere un campo del tipo MonitoredResource.

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

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

  • logName: poiché il campo logName è una stringa, non puoi seguirlo i nomi dei campi secondari.

Quando esegui una query sui campi map o struct, devi conservarne chiavi maiuscole e minuscole e la formattazione nell'espressione.

Ad esempio, jsonPayload è un campo di struct, quindi un nome di campo nidificato all'interno jsonPayload come jsonPayload.end_time è diverso da jsonPayload.endTime. Analogamente, per un campo di mappa come labels, la chiave di etichetta labels.env_name è diverso da labels.envName. Al contrario, quando interrogando il normale campo del buffer di protocollo protoPayload, senza dover conservare le maiuscole.

Per informazioni sui tipi di campo LogEntry, consulta 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'uso degli identificatori dei percorsi dei campi che fanno riferimento a oggetti o vedi 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 di risorse consulta Tipi di risorse monitorate.

Ad esempio, le VM di Compute Engine utilizzano il tipo di risorsa gce_instance e le istanze Amazon EC2 usano 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 tale campo non viene visualizzato nei log significa che il campo è mancante, undefined o predefinito:

  • Se il campo fa parte del payload della voce di log (jsonPayload o protoPayload) oppure se si trova in un'etichetta nella sezione labels di la voce di log, significa che il campo è mancante. Campo mancante non verrà visualizzato un errore, ma tutti i confronti con campi mancanti non riusciranno in silenzio.

    Esempi: jsonPayload.nearest_store, protoPayload.name.nickname

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

    Esempi: httpRequest.remoteIp, trace, operation.producer

  • In caso contrario, il campo è undefined, ovvero un errore rilevato. prima dell'uso 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 è presente esplicitamente in una voce del log:

operation.id:*

Tieni presente 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 diverso da != su un campo mancante, il risultato è FALSE:

    -- Returns FALSE
missingField!=foo

Tipi di oggetti e array

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

  • Un campo scalare memorizza un singolo valore, ad esempio 174.4 o -1. Anche un string è considerato uno scalare. Campi in cui è possibile convertire (o da) una stringa, come Duration e Timestamp, sono anch'essi 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 contiene il valore precedente, jsonPayload.x.age avrà il valore 24.

  • In un campo di array viene archiviato un elenco di valori, tutti uguali di testo. Ad esempio, un campo contenente le misure 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 usando l'operatore OR. Ad esempio, se jsonPayload.shoeSize è un campo array che memorizza {8.5, 9, 6}, il confronto:

    jsonPayload.shoeSize < 7

    equivale a:

    8.5 < 7 OR 9 < 7 OR 6 < 7

    In questo esempio, il confronto complessivo viene valutato come riuscito.

Valori e conversioni

Il primo passaggio per valutare un confronto è convertire la parte destra al tipo di campo della voce di log. I tipi di campi scalari sono consentiti in confronti, insieme a due tipi aggiuntivi i cui valori sono rappresentati come stringhe: Duration e Timestamp. Per un elenco di tipi scalari, consulta la 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

"Vero" o "false" utilizzando solo lettere maiuscole e minuscole. 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 a 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 l'asterisco stringhe di valori "NaN", "-Infinity" e "Infinity" (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 da una barra.

I valori delle stringhe devono essere racchiusi tra virgolette doppie per eseguire l'escape di quanto segue 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; "02-08-2024T15&colon;01&colon;23.045Z" (RFC 3339), "02/08/2024" (ISO 8601). Nelle espressioni di query, i timestamp nel formato RFC 3339 possono specificare un fuso orario con "Z" o ±hh:mm. I timestamp sono rappresentati con una precisione in nanosecondi.
uintNN

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

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

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

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

Tipi di campi dei log

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

  • Campi di log definiti nel tipo LogEntry e nel componente sono campi del buffer di 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, vedi il Mappatura JSON.

    Quando applichi un filtro a un campo associato al Any tipo di messaggio, il campo value viene attraversato automaticamente. Pertanto, non includerlo nella query. Per ulteriori informazioni, vedi Risoluzione dei problemi.

  • I campi del 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 senza virgolette hanno il tipo double.
    • I campi con valori true o false hanno il tipo bool.
    • I campi i cui valori sono stringhe hanno il tipo string.

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

  • I tipi Duration e Timestamp sono riconosciuti soltanto in campi del buffer di protocollo. Altrove, questi valori sono memorizzati in campi stringa.

Commenti

I commenti iniziano con due trattini (--) e il testo che li segue è ignorato fino alla fine della riga. I commenti possono essere inseriti all'inizio di 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"

  • Abilitare o disabilitare rapidamente una clausola aggiungendo o rimuovendo il commento prefisso:

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

di Gemini Advanced.

Operatori di confronto

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

  • Tutti i tipi numerici: uguaglianza e disuguaglianza hanno il loro normale significato per numeri.
  • bool: Uguaglianza indica lo stesso valore booleano. La disuguaglianza è definita true>false.
  • enum: l'uguaglianza indica lo stesso valore di enumerazione. La disuguaglianza utilizza valori numerici sottostanti dei valori letterali di enumerazione.
  • Duration: l'uguaglianza indica la stessa durata. L'iniquità si basa sulla durata. Esempio: come durate, "1s">"999ms".
  • Timestamp: uguaglianza significa lo stesso istante nel tempo. Se a e b sono Timestamp valori, a < b significa che a è precedente a b.
  • bytes: gli operanti vengono confrontati byte per byte, da sinistra a destra.
  • string: i confronti ignorano le maiuscole. Nello specifico, entrambi gli operandi dapprima normalizzato con Normalizzazione Unicode NFKC_CF e quindi di usare i confronti lessicografici. Tuttavia, le espressioni regolari cercano non sono normalizzati. Per ulteriori informazioni sulla ricerca nelle voci di log utilizzando espressioni regolari, vedi Utilizzo delle 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 utilizzano a vantaggio degli indici di log.

Limitazioni globali

Se il confronto è costituito da un singolo valore, viene chiamato restrizione 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 un 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. Questi le restrizioni 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à cerchi voci contenenti menzione di GCE_OPERATION_DONE, puoi usare la seguente query:

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

Anziché utilizzare le restrizioni globali, che possono essere lente, ti consigliamo di utilizzi funzione SEARCH integrata e le query indicizzate. 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 al valore [LOG_ID] specificato 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 per 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 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 come la specifica di un pod Database fuso orario IANA fuso orario per il tipo di dati TIMESTAMP.

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 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]: il Espressione regolare RE2 che deve contenere un gruppo di acquisizione ((...)). È necessario utilizzare un gruppo non di acquisizione (?:...) se per l'espressione regolare è necessario un raggruppamento aggiuntivo. Acquisizione multipla o nessun gruppo di acquisizione restituisce 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. Il normale l'espressione acquisisce la parte in millisecondi della stringa timestamp e trasmette in un numero intero per eseguire un confronto numerico. Tutte le voci di log che contengono vengono restituiti i timestamp in cui il campo dei millisecondi è inferiore a 500.

origine

La funzione source crea corrispondenze nelle voci di log di una determinata risorsa in delle organizzazioni, delle cartelle e della gerarchia dei progetti Google Cloud.

La funzione source non corrisponde alle risorse figlio. Ad esempio, utilizzando source(folders/folder_123) corrisponde ai log della risorsa folder_123, e non i 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 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. L'impostazione di [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 compresi tra [FIELD] e 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, tutti i log vengono scelte le voci con 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 usato un algoritmo deterministico, basato sull'hashing, per determinare se una voce di log se incluso o escluso dal campione. L'accuratezza del campione risultante dipende dalla distribuzione dei valori sottoposti ad hashing. Se i valori sottoposti ad hashing non sono distribuiti uniformemente, il campione risultante può essere distorto. Nel peggiore dei casi, quando [FIELD] contiene sempre lo stesso valore, l'esempio risultante contiene il valore [FRACTION] di tutte le voci di log le voci 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 numero massimo possibile con hash.
  • Se la frazione risultante è minore o uguale a [FRACTION], il la voce di log è inclusa nell'esempio; in caso contrario viene escluso 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 è selezionata per l'esempio, anche se [FRACTION] è 1.
  • In caso contrario, la voce di log viene trattata come se [FIELD] fosse presente nella voce di log mentre il valore predefinito è [FIELD]. Il valore predefinito è determinato da LogEntry di testo. Per ulteriori informazioni sui campi mancanti e predefiniti, consulta Campi mancanti in questo documento.

Per escludere dall'esempio le voci di log con campi predefiniti, utilizza la Operatore campo esistente, :*. 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 da una sorgente esterna. Ad esempio:

ip_in_net([FIELD], [SUBNET])

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

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

Esempio: la seguente query verifica un indirizzo IP nel payload del 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 maggiori informazioni 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 formattata come valore letterale stringa. Nel primo modulo, l'intera voce di log cercato. Nel secondo modulo devi specificare il campo della voce di log da cercare.

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

Quando viene elaborata la funzione SEARCH, la stringa query viene elaborata dal un analizzatore di testo che suddivide la stringa in token. Cloud Logging sempre esegue confronti senza distinzione tra maiuscole e minuscole, anche per i token racchiuse da apici inversi. Questo comportamento è diverso da quello di BigQuery, che mantiene le maiuscole nei token racchiusi tra barre graffe. Per informazioni sulle regole dello strumento di analisi, consulta il documento di BigQuery 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 lo stesso risultati:

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

    Le funzioni precedenti corrispondono a una voce di log quando un singolo campo contiene il token "world". Perché SEARCH esegue corrispondenze esatte e non sottostringa 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 i token non sono necessari nello stesso campo della voce di log.

    Le funzioni seguenti producono gli stessi risultati e corrispondono a una voce di log che contiene i token "hello" e "mondo":

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

  • Se specifichi il campo da cercare, la funzione SEARCH viene usata solo cerca in quel campo. Una corrispondenza si verifica quando il campo contiene tutti i token; tuttavia, l'ordine dei token non ha importanza.

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

    SEARCH(textPayload, "hello world")

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

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

    Poiché gli apici inversi vengono utilizzati nelle funzioni riportate di seguito, producono diverse risultati:

    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 il metodo SEARCH anziché eseguire una ricerca globale o una ricerca sottostringa. Tuttavia, non puoi utilizzare la funzione SEARCH per trovare una corrispondenza con i campi non di testo. Per indicazioni su come eseguire operazioni di ricerca, vedi Minimizzare le ricerche globali e con sottostringa.

Ricerca per data/ora

Nell'interfaccia, puoi impostare limiti specifici per data e ora delle voci di log da visualizzare. Ad esempio, se aggiungi quanto segue condizioni alla query, l'anteprima mostra esattamente le voci di log durante il periodo di 30 minuti indicato e non potrai scorrere di quell'intervallo di date:

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

Quando scrivi una query con un timestamp, devi utilizzare date e ore nel campo 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 giorno specifico:

timestamp > "2023-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 le espressioni regolari nel Query Builder e con Google Cloud CLI.

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

Le query con 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 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 nella 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"

=~ e !~ modificano la query in una query basata su espressione regolare, mentre il pattern a cui stai cercando di trovare una corrispondenza deve essere compreso 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"
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"
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$"

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.

Utilizzare i campi indicizzati

Logging indicizza sempre i seguenti campi LogEntry:

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

Le sezioni successive spiegano come utilizzare i campi indicizzati per ridurre al minimo di voci di log in cui eseguire la ricerca.

Ottimizza le query

Velocizza le ricerche riducendo il numero di log e di log o l'intervallo di tempo delle ricerche. Ancora meglio, puoi ridurli tutti.

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". Un'analisi più approfondita delle voci di audit log dell'attività di amministrazione, è denominato "cloudaudit.googleapis.com/activity".

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

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

Il seguente confronto è corretto. Sceglie le voci di log dal Voci del log di controllo 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: 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 corretti delle etichette esaminando una delle le 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 nel formato RFC 3339 consiste nell'utilizzare il comando GNU/Linux date:

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

Ad esempio, per cercare tra le ultime tre ore:

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

Come ulteriore esempio, per effettuare una ricerca da tre a 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 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, sono tutte ricerche di sottostringhe:

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

  • Limita la ricerca a un solo campo, anche se devi mantenere le ricerca di sottostringhe:

       textPayload:"Hello Kitty"

  • Esegui 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"

  • Utilizza 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 il testo parziale. Per 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=k8s_cluster

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

Mentre digiti, l'anteprima suggerisce il completamento dei 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 di log contenenti request_log. Tieni presente quanto segue:

  • L'operatore = rappresenta l'uguaglianza esatta. Il tipo di risorsa deve essere esattamente "k8s_cluster" tranne che per le lettere maiuscole e minuscole.
  • L'operatore : significa "ha". Il campo logName deve contenere request_log, in qualsiasi maiuscolo. 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 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 severity su almeno ERROR, che equivale a selezionare ERROR nella query menu di gravità dell'interfaccia.

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 valori tipi di risorse. L'ID log, cloudaudit.googleapis.com/activity deve essere Codificato come URL nel nome log. L'utilizzo dell'uguaglianza nel confronto velocizza eseguire una ricerca. Per ulteriori informazioni, vedi Informazioni sugli audit log.

unicorn

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

unicorn phoenix

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

textPayload:(unicorn phoenix)

Trova le voci di log il cui campo textPayload contiene sia unicorn che phoenix in qualsiasi ordine: il valore 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 entro un periodo di 30 minuti.

Risoluzione dei problemi

Problemi di sintassi

Se hai problemi con le query espressioni, controlla seguenti:

  • 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 null di 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 deve contenere caratteri speciali. In caso di dubbi, aggiungi le virgolette. 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 caratteri di escape utilizzando il comando gcloud logging, aggrega l'intera query 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.*"

    • Azione sconsigliata

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