Logging-Abfragesprache

In diesem Dokument wird auf allgemeiner Ebene die Logging-Abfragesprache beschrieben, mit der Sie Cloud Logging-Daten abfragen und filtern.

Ausführliche Informationen zum Design der Logging-Abfragesprache finden Sie in den offiziellen Google API-Spezifikationen zum Filtern.

Beispiele für häufig verwendete Abfragen finden Sie unter Beispielabfragen mit dem Log-Explorer.

Übersicht

Sie können die Logging-Abfragesprache im Log-Explorer in der Google Cloud Console, der Logging API oder die Befehlszeilenschnittstelle. Sie können die Logging-Abfragesprache verwenden, um Daten abzufragen und Filter zu schreiben, um Senken und logbasierte Messwerte zu erstellen.

Eine Abfrage ist ein boolescher Ausdruck, der eine Teilmenge aller Logeinträge angibt in der ausgewählten Google Cloud-Ressource, z. B. in einem Google Cloud-Projekt Ordner.

Sie können Abfragen basierend auf dem indexierten Feld LogEntry mit den logischen Operatoren AND und OR erstellen. Unter Verwendung des Felds resource.type in den folgenden Beispielen sieht die Grammatik der Logging-Abfragesprache so aus:

  • Einfache Einschränkung: resource.type = "k8s_cluster"

  • Konjunktive Einschränkung: resource.type = "k8s_cluster" AND severity = "ERROR"

  • Disjunktive Einschränkung: resource.type = "k8s_cluster" OR resource.type = "gce_instance"

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

  • Komplexer konjunktiver/disjunktiver Ausdruck: resource.type = "k8s_cluster" AND (severity = "ERROR" OR "error")

Das folgende Beispiel zeigt eine Abfrage:

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

Diese Abfrage erfasst Logeinträge von Compute Engine, die mindestens den Schweregrad ERROR haben und deren Feld textPayload nicht den String robot enthält. Stringvergleiche unterscheiden nicht zwischen Groß- und Kleinschreibung. Die Namen resource, severity und textPayload werden im Typ LogEntry definiert.

Syntaxnotation

Die folgenden Abschnitte geben einen Überblick über die Syntax der Logging-Abfragesprache und erläutern im Detail, wie Abfragen strukturiert sind und wie der Abgleich durchgeführt wird. In einigen Beispielen werden Kommentare verwendet, um Erläuterungen hinzuzufügen.

Wichtige Hinweise:

  • Die Länge einer Abfrage darf 20.000 Zeichen nicht überschreiten.

  • In der Logging-Abfragesprache wird die Groß- und Kleinschreibung mit Ausnahme von regulären Ausdrücken nicht berücksichtigt.

Zusammenfassung zur Syntax

Die Syntax der Logging-Abfragesprache kann in Form von Abfragen und Vergleichen betrachtet werden.

Eine Abfrage ist ein String mit einem Ausdruck:

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

Ein Vergleich ist entweder ein einzelner Wert oder ein boolescher Ausdruck:

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

Die erste Zeile ist ein Beispiel für einen Vergleich, bei dem es sich um einen einzelnen Wert handelt. Diese Vergleichstypen sind globale Beschränkungen. Jedes Feld eines Logeintrags wird implizit mit dem Wert unter Verwendung des Operators has verglichen. Wenn in diesem Beispiel ein Feld in einem LogEntry oder in seiner Nutzlast den Ausdruck "The cat in the hat" enthält, ist der Vergleich erfolgreich.

Die zweite Zeile enthält ein Beispiel für einen Vergleich mit einem booleschen Ausdruck des Formats [FIELD_NAME] [OP] [VALUE]. Ein Vergleich besteht aus drei Komponenten:

  • [FIELD_NAME] ist ein Feld in einem Logeintrag. Beispiel: resource.type.

  • [OP] ist ein Vergleichsoperator. Beispiel: =.

  • [VALUE] ist eine Zahl, ein String, eine Funktion oder ein Ausdruck in Klammern. Beispiel: "k8s_cluster". Verwenden Sie für JSON-Nullwerte NULL_VALUE.

Boolesche Operatoren

Die booleschen Operatoren AND und OR sind Kurzschlussoperatoren. Die höchste Priorität hat der Operator NOT, gefolgt von OR und AND – in dieser Reihenfolge. Die beiden folgenden Ausdrücke sind beispielsweise gleichwertig:

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

Sie können den Operator AND zwischen Vergleichen auslassen. Sie können statt des Operators NOT auch den Operator - (Minuszeichen) verwenden. Die folgenden beiden Abfragen sind beispielsweise identisch:

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

In dieser Dokumentation werden immer AND und NOT verwendet.

Für alle Filter mit Ausnahme von Filtern, die in Logansichten verwendet werden: können Sie die Operatoren AND, OR und NOT verwenden. Logansichten unterstützen nur AND und NOT Vorgänge.

Um die Regeln AND und OR im selben Ausdruck zu kombinieren, müssen Sie die Klammern zu setzen. Wenn Sie keine Klammern verwenden, funktioniert die Abfrage möglicherweise nicht wie vorgesehen.

Boolesche Operatoren müssen immer in Großbuchstaben geschrieben werden. and, or und not in Kleinbuchstaben werden als Suchbegriffe geparst.

Vergleiche

Vergleiche haben folgende Form:

[FIELD_NAME] [OP] [VALUE]

Ein Vergleich besteht aus drei Komponenten:

  • [FIELD_NAME]: ist die Feldpfadkennzeichnung eines Felds in einem Logeintrag. Im Folgenden finden Sie Beispiele für diese Kennzeichnungen:

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

    Wenn eine Komponente einer Feldpfadkennung Sonderzeichen enthält, muss die Komponente in doppelte Anführungszeichen gesetzt werden. Beispiel: compute.googleapis.com/resource_id muss in doppelte Anführungszeichen gesetzt werden, weil Es enthält einen Schrägstrich /.

    Weitere Informationen finden Sie in diesem Dokument unter Feldpfadkennzeichnungen.

  • [OP] ist einer dieser Vergleichsoperatoren:

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

Informationen zum Suchen von Logeinträgen mit regulären Ausdrücken finden Sie unter Reguläre Ausdrücke verwenden

  • [VALUE]: ist eine Zahl, ein String, eine Funktion oder ein Ausdruck in Klammern. Strings stellen beliebigen Text sowie boolesche, Aufzählungs- und Bytestring-Werte dar. [VALUE] wird vor dem Vergleich in den Feldtyp konvertiert. Verwenden Sie für JSON-Nullwerte NULL_VALUE.

Verwenden Sie folgende Syntax, um nach einem JSON-Nullwert zu filtern:

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

Wenn es sich bei [VALUE] um eine in Klammern gesetzte boolesche Kombination von Vergleichen handelt, werden der Feldname und der Vergleichsoperator auf jedes der Elemente angewendet. Beispiel:

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

Der erste Vergleich prüft, ob das Feld cat den Wert "longhair" oder "shorthair" enthält. Der zweite prüft, ob der Wert des Felds animal die Wörter "nice" und "pet" in beliebiger Reihenfolge enthält.

Feldpfadkennzeichnungen

Alle Logeinträge sind Instanzen des Typs LogEntry. Die Kennzeichnung, also die linke Seite des Vergleichs (oder deren Beginn), muss ein im Typ LogEntry definiertes Feld sein. Details zu den möglichen Kennzeichnungen und ihren Werten finden Sie im Abschnitt zum Typ "LogEntry".

Hier finden Sie die aktuelle Liste der Logeintragsfelder. Auf jedes Feld folgt gegebenenfalls die nächste Namensebene für dieses Feld:

  • 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, variable }
  • receiveTimestamp
  • resource { type, labels }
  • severity
  • sourceLocation: { file, line, function }
  • spanId
  • textPayload
  • timestamp
  • trace

Unten sehen Sie Beispiele für Feldpfadkennzeichnungen, die Sie in Ihren Vergleichen verwenden können:

  • resource.type: Wenn die erste Pfadkennzeichnung resource ist, muss die nächste Kennzeichnung ein Feld vom Typ MonitoredResource sein.

  • httpRequest.latency: Wenn die erste Pfadkennzeichnung httpRequest ist, muss die nächste Kennzeichnung ein Feld vom Typ HttpRequest sein.

  • labels.[KEY] Wenn die erste Pfadkennzeichnung labelslabels ist, muss die nächste Kennzeichnung [KEY] einer der Schlüssel aus den Schlüssel/Wert-Paaren sein, die im Feld labels angezeigt werden.

  • logName: Da das Feld logName ein String ist, kann kein Name eines Unterfelds folgen.

Wenn Sie die Felder map oder struct abfragen, müssen Sie die Groß-/Kleinschreibung und Formatierung der Schlüssel im Ausdruck beibehalten.

Beispiel: jsonPayload ist ein Struct-feld, sodass sich ein in jsonPayload verschachtelter Feldname wie jsonPayload.end_time von jsonPayload.endTime unterscheidet. Ebenso unterscheidet sich der Labelschlüssel labels.env_name für ein Zuordnungs-Feld wie labels von labels.envName. Im Gegensatz dazu müssen Sie beim Abfragen des regulären Protokollzwischenspeicherfelds protoPayload die Groß-/Kleinschreibung nicht berücksichtigen.

Informationen zu den LogEntry-Feldtypen finden Sie in der Referenz zu google.logging.v2.

Sonderzeichen

Wenn ein LogEntry-Feld Sonderzeichen enthält, muss das Logfeld in Anführungszeichen gesetzt werden. Beispiel:

jsonPayload.":name":apple

jsonPayload."foo.bar":apple

jsonPayload."\"foo\"":apple

Eine Liste der Sonderzeichen finden Sie im Abschnitt string unter Werte und Konversionen.

Weitere Informationen zur Verwendung von Feldpfadkennzeichnungen, die auf Objekte oder Arrays verweisen, finden Sie in dieser Dokumentation unter Objekt- und Arraytypen.

Überwachte Ressourcentypen

Zum Beschleunigen von Abfragen geben Sie den Typ für eine überwachte Ressource an. Eine Liste mit Ressourcentypen finden Sie unter Überwachte Ressourcentypen.

Für Compute Engine-VMs wird z. B. der Ressourcentyp gce_instance und für Amazon EC2-Instanzen der Typ aws_ec2_instance verwendet. Im folgenden Beispiel wird gezeigt, wie Sie Abfragen auf beide Arten von VMs beschränken können:

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

Die Werte überwachter Ressourcentypen in Logs sind indexiert. Durch den Abgleich mit Teilstrings verlangsamen sich die Abfragen.

Fehlende Felder

Wenn Sie in einer Abfrage einen Feldnamen verwenden und das Feld nicht in einem Logeintrag enthalten ist, kann das Feld fehlen, nicht definiert oder standardmäßig sein:

  • Wenn das Feld Teil der Nutzlast (jsonPayload oder protoPayload) des Logeintrags ist oder im Abschnitt labels des Logeintrags in einem Label enthalten ist, gilt es als fehlend. Wenn Sie ein fehlendes Feld verwenden, wird zwar keine Fehlermeldung ausgegeben, aber alle Vergleiche, die fehlende Felder verwenden, schlagen ohne Rückmeldung fehl.

    Beispiele: jsonPayload.nearest_store, protoPayload.name.nickname

  • Wenn das Feld im Typ LogEntry definiert ist, gilt das Feld als standardmäßig. Vergleiche werden durchgeführt, als wäre das Feld vorhanden und hätte seinen Standardwert.

    Beispiele: httpRequest.remoteIp, trace, operation.producer

  • Andernfalls gilt das Feld als nicht definiert, was ein Fehler ist, der vor der Verwendung der Abfrage erkannt wird.

    Beispiele: thud, operation.thud, textPayload.thud

Verwenden Sie zum Testen, ob ein fehlendes oder standardmäßiges Feld vorhanden ist, ohne jedoch einen bestimmten Wert in dem Feld zu testen, den Vergleich :*. Der folgende Vergleich ist beispielsweise erfolgreich, wenn das Feld operation.id explizit in einem Logeintrag vorhanden ist:

operation.id:*

Beachten Sie das Verhalten der folgenden Abfragen:

  • Wenn Sie den booleschen Operator NOT für ein fehlendes Feld verwenden, lautet das Ergebnis TRUE:

    -- Returns TRUE
NOT missingField=foo

  • Wenn Sie den Vergleichsoperator != für ein fehlendes Feld nutzen, lautet das Ergebnis FALSE:

    -- Returns FALSE
missingField!=foo

Objekt- und Arraytypen

Jedes Logeintragsfeld kann einen Skalar, ein Objekt oder ein Array enthalten.

  • Ein Skalarfeld speichert einen einzelnen Wert wie 174.4 oder -1. Ein string wird auch als Skalar betrachtet. Felder, die in einen (oder aus einem) String konvertiert werden können (z. B. Duration und Timestamp) enthalten ebenfalls skalare Typen.

  • Ein Objekttyp speichert eine Sammlung von benannten Werten wie den folgenden JSON-Wert:

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

    Sie können auf den Wert innerhalb eines Objekts verweisen. Wenn beispielsweise jsonPayload.x den obigen Wert enthält, hat jsonPayload.x.age den Wert 24.

  • Ein Arrayfeld speichert eine Liste von Werten – alle vom selben Typ. Zum Beispiel könnte ein Feld mit Messungen ein Array von Zahlen haben:

    {8.5, 9, 6}

    Wenn Vergleiche durchgeführt werden und [FIELD_NAME] ein Arrayfeld ist, wird jedes Element des Arrays mit [VALUE] verglichen und die Ergebnisse werden mit dem Operator OR miteinander verbunden. Wenn z. B. jsonPayload.shoeSize ein Arrayfeld ist, in dem {8.5, 9, 6} gespeichert ist, ist der Vergleich:

    jsonPayload.shoeSize < 7

    äquivalent zu:

    8.5 < 7 OR 9 < 7 OR 6 < 7

    In diesem Beispiel wird der Gesamtvergleich als erfolgreich ausgewertet.

Werte und Umwandlungen

Zur Bewertung eines Vergleichs wird zuerst der Wert auf der rechten Seite in den Typ des Logeintragsfelds umgewandelt. Skalare Feldtypen sind in Vergleichen zusammen mit den beiden zusätzlichen Typen Duration und Timestamp erlaubt. Ihre Werte werden als Strings dargestellt. Eine Liste der skalaren Typen finden Sie in der skalaren Protokollpuffertypen aufgelistet. In der folgenden Tabelle wird erläutert, welche Werte in die Logfeldtypen konvertiert werden können:

Feldtyp Zulässiger Abfragewert
bool

"True" oder "false" unabhängig von der Groß- oder Kleinschreibung. Beispiele: "True", "true"
bytes

Ein String mit einer beliebigen Bytefolge. Beispiel: "\377\377"
Duration

Ein String mit einer vorzeichenbehafteten Dezimalzahl gefolgt von einer der Einheiten "ns", "us", "ms", "s", "m" oder "h". Die Dauer wird auf die Nanosekunde genau angegeben. Beispiel: "3.2s"
enum

Der Name eines Aufzählungstypliterals unabhängig von Groß- und Kleinschreibung. Beispiel: "WARNING" ist ein Wert vom Typ LogSeverity.
double

Eine beliebige Zahl mit oder ohne Vorzeichen und mit einem Exponenten oder die speziellen Wertstrings "NaN", "-Infinity" und "Infinity" unabhängig von der Groß- oder Kleinschreibung. Beispiele: "-3.2e-8", "nan"
intNN

Eine vorzeichenbehaftete Ganzzahl innerhalb der Größe des Typs. Beispiel: "-3"
string

Ein String mit UTF-8-codiertem oder 7-Bit-ASCII-Text. Eingebetteten Anführungszeichen muss als Escapezeichen ein umgekehrter Schrägstrich vorangestellt werden.

Stringwerte müssen in Anführungszeichen gesetzt werden, um folgende Sonderzeichen zu maskieren:

  • Strings, die mit + (plus), - (minus) oder . (Punkt) beginnen.

  • Strings mit ~ (Tilde), = (ist gleich), () (Klammern), : (Doppelpunkt), > (größer als), < (kleiner als), , (Komma), . (Punkt) oder * (Sternchen).

  • Beliebige Escape-Sequenz, z. B. \t.
Timestamp

Ein String im Format RFC 3339 oder ISO 8601. Beispiele&colon; „2024-08-02T15&colon;01&colon;23.045Z“ (RFC 3339) „2024-08-02“ (ISO 8601). In Abfrageausdrücken können Sie mithilfe von Zeitstempeln im Format RFC 3339 eine Zeitzone mit "Z" oder ±hh:mm angeben. Zeitstempel werden auf die Nanosekunde genau dargestellt.
uintNN

Eine nicht vorzeichenbehaftete Ganzzahl innerhalb der Größe des Typs. Beispiel: "1234"

Wenn bei der Umwandlung ein Fehler auftritt, schlägt auch der Vergleich fehl.

Wenn für eine Umwandlung ein String erforderlich ist, können Sie eine Zahl oder einen Text ohne Anführungszeichen verwenden, sofern darin keine Sonderzeichen wie Leerzeichen oder Operatoren enthalten sind. Ebenso können Sie bei einer Umwandlung, die eine Zahl erfordert, einen aus einer Zahl bestehenden String verwenden.

Die Typen intNN und uintNN stellen Ganzzahltypen unterschiedlicher Größe wie int32 und uint64 dar. Wenn ein Wert in einen 64-Bit-Ganzzahltyp umgewandelt werden soll, muss er als String geschrieben werden, z. B. "9223372036854775807".

Typen von Logfeldern

Der Typ eines Logeintragsfelds wird so festgelegt:

  • Logfelder, die im Typ LogEntry und im Komponententyp definiert sind, sind Protokollpufferfelder. Protokollpufferfelder haben explizite Typen.

  • Zum Objekttyp protoPayload gehörende Logfelder sind ebenfalls Protokollpufferfelder und haben explizite Typen. Der Name des Protokollpuffertyps ist im Feld "@type" von protoPayload gespeichert. Weitere Informationen erhalten Sie im Abschnitt zur JSON-Zuordnung.

    Wenn Sie nach einem Feld filtern, das mit der Any Nachrichtentyp verwendet, wird das Feld value automatisch durchlaufen. Dementsprechend wird nicht in die Abfrage. Weitere Informationen finden Sie unter Fehlerbehebung.

  • Die Typen der Logfelder innerhalb von jsonPayload werden beim Empfang des Logeintrags vom Wert des Felds abgeleitet:

    • Felder, die als Werte Zahlen ohne Anführungszeichen enthalten, haben den Typ double.
    • Felder mit den Werten true oder false haben den Typ bool.
    • Felder, die als Werte Strings enthalten, haben den Typ string.

    Lange 64-Bit-Ganzzahlen werden in Stringfeldern gespeichert, da sie nicht exakt als Werte des Typs double dargestellt werden können.

  • Die Typen Duration und Timestamp werden nur in Protokollpufferfeldern erkannt. Andernfalls werden diese Werte in Stringfeldern gespeichert.

Kommentare

Kommentare beginnen mit zwei Bindestrichen (--). Der Text, der auf die Bindestriche folgt, ist bis zum Zeilenende ignoriert wird. Kommentare können am Anfang eines zwischen den Suchbegriffen und am Ende eines Filters.

Kommentare können in folgenden Fällen verwendet werden:

  • So fügen Sie Ihren komplexen Filtern Informationen zur Funktionsweise einer Klausel hinzu:

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

  • Um eine Klausel schnell zu aktivieren oder zu deaktivieren, indem Sie den Kommentar hinzufügen oder entfernen Präfix:

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

Vergleichsoperator

Die Bedeutung der Gleichheitsoperatoren (=, !=) und Ungleichheitsoperatoren (<, <=, >, >=) hängt vom zugrunde liegenden Typ des linken Feldnamens ab.

  • Alle numerischen Typen: Gleichheits- und Ungleichheitsoperatoren haben hinsichtlich Zahlen ihre normale Bedeutung.
  • bool: Gleichheit bedeutet, der boolesche Wert ist identisch. Ungleichheit wird durch true>false definiert.
  • enum: Gleichheit bedeutet, der Aufzählungswert ist identisch. Für Ungleichheit werden die zugrunde liegenden numerischen Werte der Aufzählungsliterale verwendet.
  • Duration: Gleichheit bedeutet, die Dauer ist identisch. Ungleichheit basiert auf der Dauer. Beispiel für die Dauer: "1s">"999ms".
  • Timestamp: Gleichheit bedeutet, der Zeitpunkt ist identisch. Wenn a und b Timestamp-Werte sind, bedeutet a < b, dass a zeitlich vor b liegt.
  • bytes: Die Operanden werden Byte für Byte von links nach rechts verglichen.
  • string: Bei Vergleichen wird die Groß-/Kleinschreibung ignoriert. Beide Operanden werden zuerst mit der Unicode-Normalisierung NFKC_CF normalisiert und verwenden anschließend lexikografische Vergleiche. Suchabfragen mit regulären Ausdrücken werden allerdings nicht normalisiert. Weitere Informationen zum Suchen von Logeinträgen mit regulären Ausdrücken finden Sie auf der Seite Reguläre Ausdrücke verwenden.

Der Teilstringoperator (:) gilt für string und bytes und wird wie Gleichheitsoperatoren gehandhabt. Einzige Ausnahme ist, dass der rechte Operand nur mit einem Teil des linken Felds übereinstimmen muss. Bei Teilstring-Übereinstimmungen mit indexierten Feldern werden keine Logindexe genutzt.

Globale Einschränkungen

Wenn der Vergleich aus einem einzelnen Wert besteht, wird dies als globale Einschränkung bezeichnet. Logging verwendet den Operator has (:), um zu bestimmen, ob ein Feld in einem Logeintrag oder seine Nutzlast die globale Einschränkung enthält. Wenn dies der Fall ist, ist der Vergleich erfolgreich.

Die einfachste Abfrage in Bezug auf eine globale Einschränkung ist ein einzelner Wert:

"The Cat in The Hat"

Sie können globale Einschränkungen mit den Operatoren AND und OR für komplexere Abfragen kombinieren. Wenn Sie beispielsweise alle Logeinträge aufrufen möchten, die ein Feld mit dem Wert cat und ein Feld mit entweder hat oder bat enthalten, schreiben Sie die Abfrage so:

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

In diesem Fall gibt es drei globale Einschränkungen: cat, hat und bat. Diese globalen Einschränkungen werden getrennt angewendet und die Ergebnisse werden kombiniert, als ob der Ausdruck ohne Klammern geschrieben worden wäre.

Eine globale Einschränkung bietet eine Möglichkeit, Logs nach einem bestimmten Wert abzufragen. Beispielsweise können Sie für die Suche nach Einträgen in Ihrem Aktivitätslog, die GCE_OPERATION_DONE enthalten, die folgende Abfrage verwenden:

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

Anstatt globale Einschränkungen zu verwenden, die zu Verzögerungen führen können, empfehlen wir die Verwendung der integrierten Funktion SEARCH und die Abfrage indexierter Felder. Weitere Informationen Weitere Informationen finden Sie unter Logeinträge schnell finden in diesem Dokument.

Funktionen

Sie können integrierte Funktionen als globale Einschränkungen in Abfragen nutzen: 

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

Dabei steht argument für einen Wert, einen Feldnamen oder einen Ausdruck in Klammern. Die Funktionen sind in den folgenden Abschnitten beschrieben.

log_id

Die Funktion log_id gibt Logeinträge zurück, die mit dem angegebenen Argument [LOG_ID] aus dem Feld logName übereinstimmen:

log_id([LOG_ID])

Die folgende Abfrage gibt beispielsweise alle Logeinträge, die cloudaudit.googleapis.com%2Factivity [LOG_ID] enthalten, zurück:

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

streamen

Die cast-Funktion akzeptiert zwei Parameter: das Feld LogEntry für und dem Datentyp, in den das Feld konvertiert wird:

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

Die Parameter des vorherigen Ausdrucks sind wie folgt definiert:

  • [FIELD]: Der Name eines Felds im Logeintrag, z. B. logName oder jsonPayload.a_field

  • [TYPE]: Der Datentyp, z. B. STRING, INT64, FLOAT64, BOOL.

    • TIMESTAMP oder DURATION: Einige Datentypen bieten zusätzliche Optionen wie die Angabe eines IANA-Zeitzonendatenbank Zeitzone für den Datentyp TIMESTAMP.

Die folgende Abfrage wandelt beispielsweise das Feld timestamp in einen STRING um. und gibt die Zeitzone America/New_York an:

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

regexp_extract

Verwenden Sie die Funktion regexp_extract, um den ersten Teilstring zu finden, der mit einem Regulärer Ausdruck:

REGEXP_EXTRACT([FIELD], [REGULAR_EXPRESSION])

Im vorherigen Ausdruck sind die Felder so definiert:

  • [FIELD]: Der Name eines Felds im Logeintrag, z. B. logName oder jsonPayload.a_field.
  • [REGULAR_EXPRESSION]: Die Regulärer RE2-Ausdruck, der Folgendes enthalten muss: eine Erfassungsgruppe ((...)). Eine (?:...)-Gruppe, die keine Erfassungsgruppe ist, muss verwendet werden, wenn Für den regulären Ausdruck ist eine zusätzliche Gruppierung erforderlich. Mehrere Erfassungsgruppen oder keine Erfassungsgruppen führen zu einem Fehler.

Sie können die Funktionen cast und regexp_extract verketten:

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

Im vorherigen Beispiel wird das Feld timestamp in einen String umgewandelt. Der reguläre Ausdruck erfasst den Millisekundenteil des Strings timestamp und wandelt ihn in eine Ganzzahl um, um einen numerischen Vergleich durchzuführen. Alle Logeinträge, die folgenden Text enthalten: Zeitstempel zurückgegeben werden, bei denen das Millisekundenfeld kleiner als 500 ist.

source

Die Funktion source gleicht Logeinträge aus einer bestimmten Ressource in der Organisations-, Ordner- und Google Cloud-Projekthierarchie.

Die source-Funktion stimmt nicht mit den untergeordneten Ressourcen überein. Wenn Sie beispielsweise source(folders/folder_123) gleicht Logs der Ressource folder_123 ab. und nicht Logs aus den Google Cloud-Projektressourcen in folder_123.

Verwenden Sie folgende Syntax, um Logs auf einer bestimmten Ressourcenebene abzufragen:

source(RESOURCE_TYPE/RESOURCE_ID)
Ressource Beispielabfrage
Organisation source(organizations/ORGANIZATION_ID)
Ordner source(folders/FOLDER_ID)
Google Cloud-Projekte source(projects/PROJECT_ID)

Beispiel

Mit der Funktion sample wird ein Anteil der Gesamtzahl von Logeinträgen ausgewählt:

sample([FIELD], [FRACTION])

[FIELD] ist der Name eines Felds im Logeintrag, beispielsweise logName oder jsonPayload.a_field. Der Wert des Felds bestimmt, ob der Logeintrag in die Stichprobe einbezogen wird. Der Feldtyp muss ein String oder ein numerischer Wert sein. Eine gute Wahl ist, [FIELD] auf insertId festzulegen, da jeder Logeintrag einen anderen Wert für dieses Feld hat.

[FRACTION] ist der Anteil der Logeinträge, die einzubeziehende Werte für [FIELD] enthalten. Es ist eine Zahl größer als 0,0 und kleiner oder gleich 1,0. Wenn Sie beispielsweise 0.01 angeben, enthält die Stichprobe etwa 1 % aller Logeinträge mit Werten für [FIELD]. Wenn [FRACTION] den Wert 1 hat, werden alle Logeinträge ausgewählt, die Werte für [FIELD] enthalten.

Beispiel: Durch die folgende Abfrage werden 25 % der Logeinträge des Logs syslog zurückgegeben:

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

Details: Es wird ein auf der Hash-Technologie basierender deterministischer Algorithmus verwendet, um zu bestimmen, ob ein Logeintrag in der Stichprobe enthalten oder davon ausgeschlossen ist. Die Genauigkeit der resultierenden Stichprobe hängt von der Verteilung der Hash-Werte ab. Wenn die Hash-Werte nicht gleichmäßig verteilt sind, kann die resultierende Stichprobe verzerrt sein. Im schlimmsten Fall, wenn nämlich [FIELD] immer den gleichen Wert enthält, umfasst die resultierende Stichprobe entweder die [FRACTION] aller Logeinträge oder gar keine Logeinträge.

Wenn [FIELD] in einem Logeintrag enthalten ist, dann gilt:

  • Ein Hash des Werts wird berechnet.
  • Der Hash-Wert, bei dem es sich um eine Zahl handelt, wird durch den maximal möglichen Hash-Wert geteilt.
  • Wenn der resultierende Bruch kleiner oder gleich [FRACTION] ist, wird der Logeintrag in die Stichprobe eingeschlossen. Andernfalls wird er aus der Stichprobe ausgeschlossen.

Wenn [FIELD] nicht in einem Logeintrag enthalten ist, dann gilt:

  • Wenn [FIELD] zur Nutzlast des Logeintrags oder zu den Abschnitten unter labels gehört, wird der Logeintrag nicht für die Stichprobe ausgewählt, selbst wenn [FRACTION] den Wert 1 hat.
  • Andernfalls wird der Logeintrag behandelt, als wäre [FIELD] im Logeintrag enthalten. Der Wert von [FIELD] ist dann der Standardwert, der vom Typ LogEntry bestimmt wird. Weitere Informationen zu fehlenden Feldern und Standardfeldern finden Sie in diesem Dokument unter Fehlende Felder.

Wenn Sie Logeinträge mit standardmäßigen Feldern aus der Stichprobe ausschließen möchten, verwenden Sie für vorhandene Felder den Operator :*. Die folgende Abfrage gibt 1 % der Logeinträge, in denen explizit ein Wert für field angegeben ist, als Stichprobe zurück:

field:* AND sample(field, 0.01)

Funktion "ip_in_net"

Die Funktion ip_in_net gibt an, ob eine IP-Adresse in einem Logeintrag in einem Subnetz enthalten ist. Sie könnten mit dieser Funktion erkennen, ob eine Anfrage von einer internen oder externen Quelle stammt. Beispiel:

ip_in_net([FIELD], [SUBNET])

[FIELD] ist ein Feld mit einem Stringwert im Logeintrag, das eine IP-Adresse oder einen IP-Bereich enthält. Das Feld kann sich wiederholen. In diesem Fall muss nur eines der wiederholten Felder eine im Subnetz enthaltene IP-Adresse oder einen IP-Bereich enthalten.

[SUBNET] ist eine Stringkonstante für eine IP-Adresse oder einen IP-Bereich. Wenn [SUBNET] keine gültige IP-Adresse oder kein gültiger IP-Bereich ist, tritt ein Fehler auf. Darauf wird später in diesem Abschnitt eingegangen.

Beispiel: Mit der folgenden Abfrage wird eine IP-Adresse in der Nutzlast von Logeinträgen aus dem Log my_log getestet:

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

Details: Wenn [FIELD] in einem Logeintrag fehlt, standardmäßig eingespielt wird oder keine zulässige IP-Adresse oder keinen zulässigen IP-Bereich enthält, wird "false" zurückgegeben. Weitere Informationen zu fehlenden Feldern und Standardfeldern finden Sie in diesem Dokument unter Fehlende Felder.

Beispiele für unterstützte IP-Adressen und -Bereiche:

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

SEARCH-Funktion

Mit der integrierten Funktion SEARCH können Sie Strings in Ihren Protokolldaten finden:

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

Beide Formen der SEARCH-Funktion enthalten ein query-Argument, das als String-Literal formatiert. In der ersten Form ist der gesamte Logeintrag gesucht. Im zweiten Formular geben Sie das Feld im Logeintrag an, in dem gesucht werden soll.

Sie müssen das Feld query angeben. Ist dieses Feld nicht angegeben, wird ein zurückgegeben.

Bei der Verarbeitung der SEARCH-Funktion wird der String query von einem Textanalysator verarbeitet, der den String in Tokens aufteilt. Cloud Logging immer Vergleiche ohne Berücksichtigung der Groß-/Kleinschreibung, auch für Tokens mit Backticks umschlossen. Dieses Verhalten unterscheidet sich von dem von BigQuery, wodurch die Groß- und Kleinschreibung in Tokens erhalten bleibt, die mit Gravis umschlossen sind. Informationen zu den Analyseregeln finden Sie im BigQuery-Dokument Textanalyse-Regeln:

Beachten Sie beim Erstellen einer Suche Folgendes:

  • Bei Tokens wird nicht zwischen Groß- und Kleinschreibung unterschieden. Die folgenden Funktionen erzeugen dasselbe Ergebnisse:

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

    Die vorherigen Funktionen stimmen mit einem Logeintrag überein, wenn ein einzelnes Feld den Parameter Token „world“. Da SEARCH eine genaue Übereinstimmung und keine Übereinstimmung mit einem Teilstring durchführt, stimmen die vorherigen Funktionen nicht mit einem Feld überein, dessen Wert „weltweit“ ist.

  • Wenn Sie das Feld für die Suche nicht angeben, wird die Funktion SEARCH stimmt mit einem Logeintrag überein, wenn dieser Logeintrag alle Tokens enthält. Sie können jedoch Die Reihenfolge der Tokens spielt keine Rolle und die Tokens sind nicht erforderlich, befinden sich im selben Feld des Logeintrags.

    Die folgenden Funktionen erzeugen dieselben Ergebnisse und stimmen mit einem Logeintrag überein. das die Tokens „hello“ enthält und "world":

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

  • Wenn Sie das zu durchsuchende Feld angeben, wird mit der SEARCH-Funktion nur in diesem Feld gesucht. Eine Übereinstimmung liegt vor, wenn dieses Feld alle Tokens enthält. Die Reihenfolge der Tokens spielt dabei keine Rolle.

    Die folgenden Funktionen erzeugen nur dann eine Übereinstimmung, wenn das Feld textPayload enthält die Tokens „hello“ und "world":

    SEARCH(textPayload, "hello world")

  • Wenn für eine Wortgruppe die Groß-/Kleinschreibung, aber die genaue Übereinstimmung nicht berücksichtigt wird, die Phrase in Graviszeichen setzen. Die folgenden Funktionen stimmen beispielsweise mit dem String „hallo welt“ überein:

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

    Da Graviszeichen in den folgenden Funktionen verwendet werden, erzeugen sie unterschiedliche Ergebnisse:

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

Die Logging-Abfragesprache unterstützt verschiedene Möglichkeiten, in Ihren Protokolldaten zu suchen. Bei der Suche nach einem String ist es effizienter, die Methode SEARCH-Funktion als eine globale Suche oder eine Teilstring-Suche durchzuführen. Allerdings können Sie die SEARCH-Funktion nicht zum Abgleich von Nicht-Textfeldern verwenden. Anleitungen zur Durchführung von Suchvorgängen finden Sie unter Minimieren Sie globale Suchen und Teilstring-Suchanfragen.

Nach Zeitraum suchen

In der Benutzeroberfläche können Sie Datums- und Uhrzeitbereiche für die Logeinträge festlegen, die angezeigt werden sollen. Wenn Sie beispielsweise Folgendes hinzufügen: Bedingungen an Ihre Abfrage an, werden in der Vorschau genau die Logeinträge angezeigt, innerhalb der angegebenen 30 Minuten und können nicht nach außen des Zeitraums:

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

Wenn Sie eine Abfrage mit einem Zeitstempel schreiben, müssen Sie Datum und Uhrzeit im Feld wie im vorherigen Format dargestellt.

Sie können Logeinträge auch mit timestamp-Kürzeln suchen. Beispielsweise haben Sie die Möglichkeit, ein Datum mit einem Vergleichsoperator einzugeben, um alle Logeinträge nach einem bestimmten Tag abzurufen:

timestamp > "2023-11-29"

Reguläre Ausdrücke verwenden

Sie haben die Möglichkeit, mithilfe von regulären Ausdrücken Abfragen und Filter für Senken, Messwerte sowie überall dort zu erstellen, wo Logfilter verwendet werden. So können Sie beispielsweise reguläre Ausdrücke in der Query Builder und mit Google Cloud CLI

Ein regulärer Ausdruck ist eine Folge von Zeichen, die eine Suche definieren. Die Logging-Abfragesprache verwendet die RE2-Syntax. Eine vollständige Erläuterung der RE2-Syntax finden Sie im RE2-Wiki auf GitHub.

Abfragen mit regulären Ausdrücken haben folgende Merkmale:

  • Es können nur Felder vom Typ "String" mit einem regulären Ausdruck abgeglichen werden.

  • Es wird keine Stringnormalisierung ausgeführt. Beispielsweise ist kubernetes nicht dasselbe wie KUBERNETES. Weitere Informationen finden Sie im Abschnitt Vergleichsoperatoren.

  • Bei Abfragen wird zwischen Groß- und Kleinschreibung unterschieden und sie sind nicht standardmäßig verankert.

  • Boolesche Operatoren können zwischen mehreren regulären Ausdrücken auf der rechten Seite des Vergleichsoperators für reguläre Ausdrücke (=~ und !~) verwendet werden.

Eine Abfrage mit einem regulären Ausdruck hat die folgende Struktur:

Entspricht einem Muster:

jsonPayload.message =~ "regular expression pattern"

Entspricht keinem Muster:

jsonPayload.message !~ "regular expression pattern"

=~ und !~ ändern die Abfrage in eine Abfrage mit einem regulären Ausdruck. Das Muster, das Sie abgleichen möchten, muss in doppelte Anführungszeichen gesetzt werden. Bei der Abfrage von Mustern, in denen doppelte Anführungszeichen enthalten sind, müssen Sie sie mit einem umgekehrten Schrägstrich maskieren.

Beispiele für die Abfrage von Logs mit regulären Ausdrücken

Abfragetyp Beispiel
Standardabfrage sourceLocation.file =~ "foo"
Abfrage mit Suche ohne Berücksichtigung der Groß- und Kleinschreibung labels.subnetwork_name =~ "(?i)foo"
Abfrage mit Anführungszeichen jsonPayload.message =~ "field1=\"bar.*\""
Abfrage mit einem booleschen or labels.pod_name =~ "(foo|bar)"
Abfrage mit Anchors logName =~ "/my%2Flog$"
Abfrage entspricht keinem Muster labels.pod_name !~ "foo"
Abfrage mit einem booleschen Operator labels.env =~ ("^prod.*server" OR "^staging.*server")
Abfrage, die mit einem Wert beginnt logName =~ "^foo"
Abfrage, die mit einem Wert endet logName =~ "foo$"

Logeinträge schnell finden

So finden Sie Logeinträge effizient:

  • Erstellen Sie eine Abfrage mit indexierten Feldern.
  • Minimieren Sie die Anzahl der Logeinträge, die geprüft werden sollen.

Indexierte Felder verwenden

Logging indexiert immer die folgenden LogEntry:

Sie können auch benutzerdefinierte indexierte Felder einen beliebigen Log-Bucket.

In den nächsten Abschnitten wird erläutert, wie Sie mit indexierten Feldern Anzahl der zu durchsuchenden Logeinträge.

Abfragen optimieren

Sie können Suchanfragen beschleunigen, indem Sie die Anzahl der Logs oder Logeinträge oder den Zeitraum jeder Suche reduzieren. Und noch besser: Sie können alle 3.

Beispiel: Den richtigen Lognamen verwenden

Geben Sie das Log mit den relevanten Logeinträgen an. Wichtig ist, dass Sie den tatsächlichen Lognamen kennen. Diesen finden Sie in Ihren Logeinträgen. Beispiel: Der Parameter In der Vorschau sehen Sie, dass der Bereich "Compute Engine" ein Log mit dem Namen „Aktivität“. Bei genauerer Prüfung der Logeinträge für Administratoraktivitäten sehen Sie, dass das Log tatsächlich „cloudaudit.googleapis.com/activity“ heißt.

Der folgende Vergleich ist falsch. Es wird keine Übereinstimmung zurückgegeben, da der Logname falsch ist:

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

Der folgende Vergleich ist richtig. Damit werden Logeinträge aus dem Audit-Log für Administratoraktivitäten ausgewählt. Wichtig ist, dass der Logname wie folgt URL-codiert ist:

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

Beispiel: Die richtigen Logeinträge auswählen

Wenn Sie wissen, dass die gewünschten Logeinträge aus einer bestimmten VM-Instanz stammen, geben Sie die Instanz an. Prüfen Sie die Richtigkeit der Labelnamen in einem der zu durchsuchenden Logeinträge. Im folgenden Beispiel ist instance_id eines der indexierten Labels:

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

Beispiel: Den richtigen Zeitraum auswählen

Geben Sie einen Zeitraum für die Suche an. Nützliche Zeitstempel im RFC 3339-Format lassen sich schnell mit dem GNU/Linux-Befehl date festlegen:

$ 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

Verwenden Sie die Werte dieser Zeitstempel in den folgenden Abfragen. Wenn Sie einen für Logging akzeptablen Zeitstempel erstellen möchten, ersetzen Sie das Leerzeichen zwischen Datum und Uhrzeit durch den Buchstaben T.

Durchsuchen Sie z. B. die Einträge der vergangenen drei Stunden:

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

Oder durchsuchen Sie den Zeitraum vor drei bis fünf Stunden:

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

Globale und Teilstring-Suchanfragen minimieren

Kürzen Sie Abfragen bei der Eingabe nicht ab.

Beispiel: Keine globalen Suchanfragen verwenden

Angenommen, Sie suchen nach einem Logeintrag mit dem Text "Hello, Kitty" in der Nutzlast:

  • Falsch: Verwenden Sie keine globale Suchanfrage. Sie sind aus einem Grund alle Teilstring-Suchanfragen:

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

  • Richtig: Begrenzen Sie die Suche auch dann auf ein einzelnes Feld, wenn Sie eine Teilstring-Suche durchführen müssen:

       textPayload:"Hello Kitty"

  • Richtig: Führen Sie nach Möglichkeit einen Gleichheitstest durch:

       textPayload = "Hello Kitty"

  • Richtig: Referenzieren Sie einzelne Felder in einer Nutzlast, wenn die Log-Einträge über strukturierte Nutzlasten verfügen:

       jsonPayload.my_favorite_cat = "Hello Kitty"

  • Richtig: Schränken Sie die Suche durch Verwendung eines indexierten Felds ein:

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

  • Richtig: Verwenden Sie die SEARCH-Funktion und geben Sie den vollständigen Text für die Übereinstimmung an. Bei der Funktion SEARCH wird eine Übereinstimmung ohne Berücksichtigung der Groß- und Kleinschreibung ausgeführt:

      SEARCH("Hello Kitty")

    Verwenden Sie nicht die Funktion SEARCH und geben Sie einen Teil des Textes an. Für Beispiel: Die folgende Funktion stimmt nicht mit „Hello Kitty“ überein.

      SEARCH("Hello Kit")

In Beispielen suchen

Die gezeigten Logeinträge stimmen mit einer Abfrage überein. Wenn das Menü Zu Zeit springen einen Wert enthält, wird in der Anzeige zu dieser Zeit gescrollt. Hier einige Beispiele für Abfragen:

resource.type=k8s_cluster

Hiermit werden alle Google Kubernetes Engine-Logeinträge zurückgegeben. Die Ressourcentypen entnehmen Sie der Liste der überwachten Ressourcen.

Während der Eingabe werden in der Vorschau Vorschläge für Felder wie resource.type eingeblendet.

resource.type=k8s_cluster AND logName:request_log

Hiermit werden Logeinträge für Google Kubernetes Engine-Cluster aus Logs zurückgegeben, deren Name request_log enthält. Beachten Sie Folgendes:

  • Der Operator = steht für genaue Gleichheit. Der Ressourcentyp muss genau mit "k8s_cluster" übereinstimmen. Die Groß-/Kleinschreibung wird nicht beachtet.
  • Der Operator : steht für "has" (enthält). Das Feld logName muss request_log enthalten. Die Groß-/Kleinschreibung wird nicht beachtet. Der tatsächliche Log-Name ist deutlich länger. Der Operator : kann Suchanfragen verlangsamen.
  • Die beiden Vergleiche werden durch AND verbunden. Sie können auch OR verwenden. Wenn Sie den Operator weglassen, gilt standardmäßig AND.
resource.type = (gce_instance OR aws_ec2_instance) AND severity >= ERROR

Hiermit werden Logeinträge mit einem der beiden Ressourcentypen "Compute Engine-VM-Instanz" oder "AWS EC2-VM-Instanz" zurückgegeben. Für die Logeinträge muss mindestens die severity (Wichtigkeitsstufe) ERROR gelten. Das entspricht in der Abfrageoberfläche der Auswahl von ERROR im Menü für Wichtigkeitsstufen.

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

Hiermit werden alle Audit-Log-Einträge zu Administratoraktivitäten im Projekt [PROJECT_ID] zurückgegeben. Alle Audit-Logs eines Projekts verwenden denselben Namen, haben aber unterschiedliche Ressourcentypen. Die Log-ID cloudaudit.googleapis.com/activity muss URL-codiert und im Lognamen enthalten sein. Durch Verwendung eines Gleichheitsoperators im Vergleich beschleunigen Sie die Suche. Weitere Informationen finden Sie unter Informationen zu Audit-Logs.

unicorn

Hiermit werden Logeinträge zurückgegeben, die in einem der Felder unicorn enthalten. Die Groß-/Kleinschreibung wird nicht beachtet. Ein Suchbegriff, der nicht Teil eines Feldvergleichs ist, bildet eine Abfrage an "alle Felder".

unicorn phoenix

Hiermit werden Logeinträge zurückgegeben, die in einem der Felder unicorn und phoenix enthalten.

textPayload:(unicorn phoenix)

Hiermit werden Logeinträge zurückgegeben, deren Feld textPayload sowohl unicorn als auch phoenix in beliebiger Reihenfolge enthält. Zwischen den beiden Wörtern wird standardmäßig der Operator AND angenommen.

textPayload:"unicorn phoenix"

Hiermit werden Logeinträge zurückgegeben, deren Feld textPayload den String "unicorn phoenix" enthält.

NOT textPayload: "unicorn phoenix"

Hiermit werden Logeinträge zurückgegeben, deren Feld textPayload den String "unicorn phoenix" nicht enthält. Diese Art der Abfrage reduziert unerwünschte Logeinträge.

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

Hiermit werden Logeinträge innerhalb eines 30-Minuten-Zeitraums zurückgegeben.

Fehlerbehebung

Syntaxprobleme

Prüfen Sie bei Problemen mit Ausdrücken von Abfragen Folgendes:

  • Die Abfragen erfüllen die Syntaxregeln hinsichtlich entsprechender Klammern und Anführungszeichen.

  • Die Feldnamen für die Log-Einträge sind korrekt geschrieben.

  • Boolesche Operatoren sind in Großbuchstaben angegeben (AND, OR, NOT).

  • Verwenden Sie unbedingt NULL_VALUE, um JSON-Nullwerte darzustellen.

  • Boolesche Ausdrücke, die als globale Einschränkungen oder als rechte Seite in Vergleichen verwendet werden, sollten der Übersichtlichkeit halber in Klammern gesetzt werden. Beispiel: Der Parameter sehen die folgenden beiden Abfragen gleich aus, sind es aber nicht:

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

  • Text ohne Anführungszeichen darf keine Sonderzeichen enthalten. Fügen Sie im Zweifelsfall doppelte Anführungszeichen hinzu. Im folgenden Beispiel wurde der erste Vergleich ist illegal des eingebetteten Teilstring-Operators (:) festgelegt. Der Vergleich muss mit Anführungszeichen:

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

  • Die Google Cloud CLI benötigt in doppelte Anführungszeichen setzen. Wenn Sie mit dem Befehl gcloud logging doppelte Anführungszeichen als Maskierungszeichen von Sonderzeichen verwenden möchten, setzen Sie den gesamten Filter stattdessen in einfache Anführungszeichen:

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

  • Wenn Sie nach einem Feld filtern, das mit der Any Nachrichtentyp verwendet, wird das Feld value automatisch durchlaufen. Dementsprechend wird Nehmen Sie value nicht in die Abfrage auf.

    Beispiel: Der Parameter Status in einem AuditLog Nachricht enthält ein details-Feld vom Typ google.protobuf.Any. Um das Feld details abzufragen, lassen Sie das Feld value bei der Angabe der Filter:

    • Richtig

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

    • Nicht empfohlen

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