Erweiterte Logfilter

In diesem Leitfaden erfahren Sie, wie Sie erweiterte Logfilter erstellen. Dabei handelt es sich um Ausdrücke, mit denen Sie eine Reihe von Logeinträgen aus einer beliebigen Anzahl von Logs angeben können. Erweiterte Logfilter können in der Loganzeige, der Stackdriver Logging API oder der Befehlszeile verwendet werden.

Informationen zu einfacheren Filteroptionen finden Sie unter Einfache Logfilter.

Eine Liste der empfohlenen Filter zum Suchen von Logs finden Sie unter Bibliothek der erweiterten Filter. Einige der in dieser Anleitung verlinkten Ressourcen stehen ggf. nur auf Englisch zur Verfügung.

Einführung

Erweiterte Logfilter sind boolesche Ausdrücke, die Ihnen ermöglichen, eine Teilmenge aller Logeinträge Ihres Projekts anzugeben. Sie können damit die folgenden Aufgaben ausführen:

  • Logeinträge aus bestimmten Logs oder Logdiensten auswählen
  • Logeinträge innerhalb eines Zeitraums auswählen
  • Logeinträge auswählen, die Bedingungen für Metadaten oder benutzerdefinierte Felder erfüllen
  • Einen Prozentsatz aller Logeinträge als Stichprobe auswählen

Erste Schritte mit erweiterten Logfiltern

So verwenden Sie erweiterte Logfilter in der Loganzeige:

  1. Gehen Sie in der GCP Console auf die Seite Stackdriver Logging > Logs (Loganzeige):

    Loganzeige öffnen

  2. Wählen Sie oben auf der Seite ein vorhandenes GCP-Projekt aus oder erstellen Sie ein neues Projekt.

  3. Wählen Sie in den Drop-down-Menüs die Ressource aus, deren Logs Sie ansehen möchten.

  4. Klicken Sie auf den Drop-down-Pfeil (▾) ganz rechts im Suchfilterfeld und wählen Sie Convert to advanced filter (In erweiterten Filter umwandeln) aus.

    In erweiterten Logfilter konvertieren

Unten sehen Sie eine Abbildung der Oberfläche für erweiterte Logfilter:

Erweiterte Benutzeroberfläche für Logfilter

Sie erkennen diese Filteroberfläche an der Schaltfläche Submit Filter (Filter senden) und daran, dass die Logauswahlmenüs fehlen. In der Loganzeige werden Logeinträge angezeigt, die alle im Filter angegebenen Bedingungen erfüllen.

Hier ein einfaches Beispiel eines erweiterten Logfilters:

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

Dieser Filter 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.

Vorschläge und Hervorhebungen während der Eingabe Wenn Sie einen erweiterten Logfilter in die Loganzeige eingeben, werden möglicherweise Vorschläge für bestimmte Logeintragsfelder angezeigt. Die Vorschläge stammen sowohl aus der Filtersprache als auch aus den tatsächlich in der Loganzeige geladenen Logeinträgen. Zur Auswahl eines Vorschlags drücken Sie TAB. Wenn keine Vorschläge angezeigt werden, kann das Drücken von CTRL + SPACE (STRG + Leertaste) helfen. Die unterschiedlichen Teile eines Filterausdrucks sind in verschiedenen Farben markiert. Ein rot markierter Ausdruck weist darauf hin, dass der bisher eingegebene Filter möglicherweise einen Fehler enthält oder unvollständig ist.

Text ohne Anführungszeichen: Textstrings, die weder Leerzeichen noch bestimmte Sonderzeichen enthalten, können Sie ohne Anführungszeichen eingeben. Dies wird als Text ohne Anführungszeichen bezeichnet. Beispiele hierfür sind die oben angegebenen Begriffe ERROR und robot. Der String "v1.compute.instances.insert" ist aufgrund der enthaltenen Punkte in Anführungszeichen gesetzt. Wenn Sie in einen String Anführungszeichen einbeziehen möchten, stellen Sie den Anführungszeichen einen umgekehrten Schrägstrich ("\") voran.

Best Practice: Setzen Sie Strings, die Sie mit Feldwerten vergleichen, in Anführungszeichen. Sie vermeiden dadurch eine versehentliche Änderung der Bedeutung eines Vergleichs. Derartige Fehler lassen sich mitunter nur schwer ermitteln und beheben. Sie können die Anführungszeichen bei Wörtern weglassen, die aus einem Buchstaben gefolgt von einer Reihe von Buchstaben, Ziffern oder Unterstrichen (_) bestehen.

Tastatur verwenden: Bei Verwendung der Tastatur zur Eingabe erweiterter Logfilter in das Suchfilterfeld gelangen Sie zu den anderen Elementen der Oberfläche (z. B. Drop-down-Menüs der Zeitraumauswahl, dem Drop-down-Pfeil (▾) ganz rechts im Suchfilterfeld oder der Schaltfläche Filter senden), indem Sie durch Drücken von ESC den Bearbeitungsmodus beenden und dann TAB drücken.

Syntax der erweiterten Logfilter

In diesem Abschnitt wird die Struktur der erweiterten Filter erläutert. Darüber hinaus wird gezeigt, wie Vergleiche durchgeführt werden.

Syntaxnotation

Die Syntax des erweiterten Logfilters lässt sich mithilfe der folgenden Notation beschreiben:

  • a = e bedeutet, dass a ein Name für den Ausdruck e ist.
  • a b bedeutet "a gefolgt von b".
  • a | b bedeutet "a oder b".
  • ( e ) wird für Gruppierungen verwendet.
  • [ e ] bedeutet, dass e optional ist.
  • { e } bedeutet, dass e nicht oder mehrere Male wiederholt werden kann.
  • "abc" bedeutet, dass abc wie vorgegeben enthalten sein muss.

Zusammenfassung zur Syntax

In diesem Abschnitt erhalten Sie eine kurze Übersicht über die Syntax erweiterter Filter. Es wird hier nicht auf alle Details eingegangen. Diese werden jedoch in den nachfolgenden Abschnitten erläutert:

Ein erweiterter Logfilter ist eine Zeichenfolge, die einen Ausdruck enthält:

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

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 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 ist ein Beispiel für einen Vergleich, bei dem es sich um einen booleschen Ausdruck der Form [FIELD_NAME] [OP] [VALUE] handelt. Die Elemente des Vergleichs sind nachfolgend beschrieben:

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

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

  • [VALUE]: ist eine Zahl, ein String, eine Funktion oder ein Ausdruck in Klammern. Zum Beispiel "gae_app".

In den folgenden Abschnitten wird näher auf Filter und deren Übereinstimmung eingegangen.

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 den Operator NOT auch durch den Operator - (Minuszeichen) ersetzen. Die folgenden beiden erweiterten Filter 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.

Vergleiche

Vergleiche haben folgende Form:

[FIELD_NAME] [OP] [VALUE]

Die Elemente des Vergleichs sind nachfolgend beschrieben:

  • [FIELD_NAME]: ist der Pfadname eines Felds in einem Logeintrag. Beispiele für den Feldnamen sind:

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

    Weitere Informationen finden Sie unter Feldpfadkennzeichnungen.

  • [OP]: ist einer der folgenden Vergleichsoperatoren:

    =           # equal
    !=          # not equal
    > < >= <=   # numeric ordering
    :           # "has" matches any substring in the log entry field
    
  • [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.

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 = ("siamese" OR "shorthair")
    jsonPayload.animal : ("nice" AND "pet")

Der erste Vergleich überprüft, ob das Feld cat den Wert "siamese" oder "shorthair" hat. 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 labels 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.

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

Überwachte Ressourcentypen

Geben Sie einen überwachten Ressourcentyp an, um die Suche zu beschleunigen. Eine Liste mit Ressourcentypen finden Sie unter Überwachte Ressourcentypen.

Bei Compute Engine-VMs wird zum Beispiel der Ressourcentyp gce_instance und bei Amazon EC2-Instanzen der Typ aws_ec2_instance verwendet. Im folgenden Beispiel ist zu sehen, wie Sie Suchanfragen 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 einem Filter 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 des Filters 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:*

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, indem {8.5, 9, 6} gespeichert ist, ist der Vergleich:

    jsonPayload.shoeSize < 7
    

    gleichbedeutend mit:

    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. Die skalaren Typen sind in der Liste der skalaren Protokollpuffertypen zu finden. In der folgenden Tabelle wird erläutert, welche Werte in Log-Feldtypen umgewandelt werden können:

Feldtyp Zulässiger Filterwert
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 der 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.
Timestamp Ein String im RFC 3339-Format. Beispiel: "2014-10-02T15:01:23.045Z" In Filterausdrücken können Sie mithilfe von Zeitstempeln 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ößen wie int32 und uint64 dar. Wenn Sie einen Wert schreiben, der in einen 64-Bit-Ganzzahltyp umgewandelt werden soll, schreiben Sie den Wert nach Möglichkeit als String, beispielsweise "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.

  • 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, die als Werte true oder false enthalten, 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.

Vergleichsoperator

Die Bedeutung der Gleichheitsoperatoren (=!=) und der 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: Vergleiche erfolgen ungeachtet der Groß-/Kleinschreibung. Beide Operanden werden zuerst mit der Unicode-Normalisierung NFKC_CF normalisiert und verwenden anschließend lexikografische Vergleiche.

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.

Der einfachste erweiterte Filter 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 kombinieren, um einen komplexeren Filter zu erhalten. Wenn Sie beispielsweise alle Logeinträge anzeigen lassen möchten, die ein Feld mit dem Wert cat und ein Feld mit entweder hat oder bat enthalten, schreiben Sie den Filter 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 einfache Möglichkeit, um Ihre Logs nach einem bestimmten Wert zu durchsuchen. Für die Suche nach Einträgen in Ihrem Aktivitätslog, die GCE_OPERATION_DONE enthalten, können Sie beispielsweise den folgenden Filter verwenden:

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

Obwohl globale Einschränkungen einfach sind, können sie langsam sein. Weitere Informationen erhalten Sie unter Logeinträge schnell finden.

Funktionen

Sie können integrierte Funktionen in erweiterten Filtern als globale Einschränkungen verwenden:

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

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

Funktion "sample"

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 Prozent 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 den folgenden Filter 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 Hashing 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 Hashwert, bei dem es sich um eine Zahl handelt, wird durch den maximal möglichen Hashwert 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 unter Fehlende Felder.

Um Logeinträge mit standardmäßigen Feldern aus der Stichprobe auszuschließen, verwenden Sie für vorhandene Felder den Operator :*. Der folgende Filter gibt 1 Prozent 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 dem folgenden Filter 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 bzw. keinen zulässigen IP-Bereich enthält, wird "false" zurückgegeben. Weitere Informationen zu fehlenden und standardmäßigen Feldern finden Sie unter Fehlende Felder.

Nachfolgend sehen Sie Beispiele der unterstützten 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

Nach Zeitraum suchen

In der erweiterten Filteroberfläche können Sie Bereiche für das Datum und die Uhrzeit der anzuzeigenden Logeinträge festlegen. Wenn Sie in den Filter beispielsweise die folgenden Bedingungen einfügen, werden in der Loganzeige nur die Logeinträge des angegebenen 30-Minuten-Zeitraums aufgelistet. Scrollen außerhalb des Datumsbereichs ist in diesem Fall nicht möglich.

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

Geben Sie das Datum und die Uhrzeit beim Schreiben von Filtern mit Zeitstempel genau wie oben gezeigt an. Wählen Sie außerdem in der Zeitbereichswahl im Suchfilterfeld die Option Keine Beschränkung aus.

Logeinträge schnell finden

Gehen Sie beim Filtern oder Abfragen von Logeinträgen wie folgt vor:

  • Suchen Sie nach indexierten Feldern.
  • Minimieren Sie die Anzahl der zu durchsuchenden Logeinträge.

Indexierte Felder verwenden

Geben Sie für indexierte Felder exakte Werte an. Verwenden Sie keine Teilstring-Übereinstimmungen. Die folgenden Logeintragsfelder sind indexiert:

Temporäre Feldindizes

Nach dem Empfang der Logeinträge in Stackdriver Logging sind vorübergehend drei zusätzliche Logeintragsfelder teilweise indexiert. Die Suche in diesen Feldern ist mitunter nützlich, um schnell auf Systemprobleme zu reagieren. Die Indexierung dieser drei Felder in Stackdriver Logging kann sich ohne vorherige Mitteilung ändern:

  • severity: Die Werte für die Wichtigkeitsstufen von NOTICE (100) bis EMERGENCY (900) sind indexiert. Suchen Sie nur nach Werten im indexierten Bereich, um den Index zu nutzen.

  • httpRequest.status: Statuswerte von 201 bis 511 sind indexiert. Suchen Sie nur nach Werten im indexierten Bereich, um den Index zu nutzen.

  • operation.id: Alle Werte in diesen Feldern sind indexiert. Durchsuchen Sie dieses Feld mit dem Gleichheitsoperator, um den Index zu nutzen. Verwenden Sie keine Teilstring-Suchanfragen.

Wenn Sie diese Felder in neuen Logeinträgen routinemäßig durchsuchen, sollten Sie gegebenenfalls mithilfe des Felds timestamp auch den Suchzeitraum begrenzen.

Anzahl der Logs/Logeinträge sowie den Zeitraum reduzieren

Sie können Suchanfragen beschleunigen, indem Sie die Anzahl der Logs oder Logeinträge oder den Zeitraum jeder Suche reduzieren. Optimalerweise reduzieren Sie alle drei.

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. Die Loganzeige gibt beispielsweise an, dass im Compute Engine-Abschnitt ein Log namens "activity_log" enthalten ist. Bei genauerer Überprüfung der Einträge des Aktivitätslogs sehen Sie, dass das Log tatsächlich "compute.googleapis.com/activity_log" 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_log"   # WRONG!

Der folgende Vergleich ist richtig. Dabei werden Logeinträge im Aktivitätslog ausgewählt. Wichtig ist, dass der Logname wie folgt URL-codiert ist:

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

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. Überprüfen Sie die Richtigkeit der Labelnamen in einem der zu durchsuchenden Logeinträge. Im folgenden Beispiel ist instance_id eines der indexierten Labels:

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

Geben Sie einen Wert für den Ressourcentyp an. Andernfalls wird der Index nicht für den Vergleich von instance_id verwendet.

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
2016-06-27 17:39:00-04:00
$ date --rfc-3339=s --date="3 hours ago"
2016-06-27 14:40:00-04:00
$ date --rfc-3339=s --date="5 hours ago"
2016-06-27 12:40:00-04:00

Verwenden Sie die Werte dieser Zeitstempel in den folgenden Filtern. Ersetzen Sie das Leerzeichen zwischen dem Datum und der Uhrzeit durch den Buchstaben T, um einen von Stackdriver Logging unterstützten Zeitstempel zu erstellen.

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

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

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

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

Ein weiteres Beispiel zur Verwendung von Zeitstempeln finden Sie unter Temporäre Feldindexe.

Globale und Teilstring-Suchanfragen minimieren

Kürzen Sie Logfilter bei der Eingabe nicht ab.

Beispiel: Keine Teilstrings in indexierten Feldern verwenden

Angenommen, Sie suchen nach einem Logeintrag vom Apache2-Webserver. Sie wissen, dass die Apache-Logs apache-access und apache-error heißen. Wie gehen Sie vor?

  • Falsch: Verwenden Sie keine Teilstring-Übereinstimmung, um die Eingabe zu beschleunigen:

        logName:apache   # THIS CAUSES A SLOW SEARCH!
    
  • Richtig: Verwenden Sie zum Durchsuchen indexierter Felder exakte Übereinstimmungen:

        logName = ("projects/my-project-id/logs/apache-access" OR
                   "projects/my-project-id/logs/apache-error")
    

Teilstring-Suchanfragen in indexierten Feldern verlangsamen den Suchvorgang.

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. Ein Grund ist, dass es sich dabei ausnahmslos um Teilstring-Suchanfragen handelt:

        "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 Logeinträ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"
    

Beispiele durchsuchen

Die aufgeführten Logeinträge stimmen mit dem erweiterten Logfilter im Textfeld überein. Wenn das Menü Zu Datum springen einen Wert enthält, wird in der Anzeige zu diesem Zeitpunkt gescrollt. Hier ein paar Filterbeispiele:

resource.type=gae_app

Hiermit werden dieselben Logeinträge zurückgegeben, die Sie auch auf der einfachen Filteroberfläche sehen würden, wenn Sie im Menü mit den Ressourcenlogs die Option GAE-Anwendung (alle Modul-IDs) und im Menü mit den Lognamen Alle Logs auswählen. Die Ressourcentypen entnehmen Sie der Liste der überwachten Ressourcen.

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

resource.type=gae_app AND logName:request_log

Hiermit werden Logeinträge für App Engine-Apps 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 "gae_app" ü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 Logname 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. Dies entspricht in der einfachen Filteroberfläche der Auswahl von ERROR im Menü für Wichtigkeitsstufen. Sie können auf der einfachen Filteroberfläche jeweils nur die Logs eines einzigen Ressourcentyps ansehen.

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 Audit-Logs abrufen.

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 den String "unicorn phoenix" textPayload enthält. Dieser Filter ist mit dem Filter der einfachen Filteroberfläche identisch.

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

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

Fehlerbehebung

Tastaturnavigation

Wenn Sie eine Tastatur zum Eingeben eines erweiterten Filters in das Suchfilterfeld verwenden und andere Menüs auf der Seite aufrufen müssen, drücken Sie ESC, um den Bearbeitungsmodus zu verlassen. Dann drücken Sie TAB, um zu den anderen Optionen zu gelangen.

Syntaxprobleme

Prüfen Sie bei Problemen mit erweiterten Filtern Folgendes:

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

  • Die Feldnamen für die Logeinträge sind korrekt geschrieben.

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

  • Boolesche Ausdrücke, die als globale Einschränkungen oder als rechte Seite in Vergleichen verwendet werden, sollten der Übersichtlichkeit halber in Klammern gesetzt werden. Die beiden Filter unten sehen beispielsweise gleich aus, sind aber unterschiedlich:

    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. Der erste Vergleich unten ist beispielsweise aufgrund des eingebetteten Teilstring-Operators (:) unzulässig. Der Vergleich muss mit Anführungszeichen geschrieben werden:

    insertId = abc:def  # ILLEGAL!
    insertId = "abc:def"
    
  • Bei gcloud logging muss der Filter in doppelte Anführungszeichen gesetzt werden. Wenn Sie mit dem gcloud logging-Befehl 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."'
    
  • Suchausdrücke in den einfachen Filtern der Loganzeige unterscheiden sich von Suchausdrücken in erweiterten Filtern: Weitere Informationen finden Sie im Abschnitt Unterschiede zwischen einfachen und erweiterten Filtern.

  • Wenn Sie einen Filter schreiben, der einen Zeitstempel enthält, wählen Sie in der Zeitraumauswahl die Option Keine Beschränkung aus.

Hat Ihnen diese Seite weitergeholfen? Teilen Sie uns Ihr Feedback mit:

Feedback geben zu...

Stackdriver Logging