Cloud Trace-Filter

Mithilfe von Trace-Filtern können Sie eine Reihe von Traces aus Cloud Trace auswählen. Sie haben folgende Möglichkeiten, Trace-Filter zu verwenden:

Als Filterparameter in einer Abfrage mit der API-Methode list.
Als Anfragefilterparameter beim Erstellen eines Analyseberichts.
Als Filter-Feld auf der Seite Trace Explorer. Informationen zum Erstellen und Ändern dieser Filter finden Sie unter Letzte Traces anzeigen.

Hinweis: Die Filterleiste auf der Seite Trace Explorer ist menübasiert und die Optionen hängen von Ihrer Konfiguration ab. Die menübasierten Optionen beinhalten in der Regel das Filtern nach HTTP-Status und HTTP-Methode. Wenn Sie die App Engine verwenden, sind auch Optionen für Dienst und Version verfügbar. Diese Optionen sind bei Verwendung von Cloud Trace-Filtern nicht verfügbar.

Mit Filtern können Sie eine oder mehrere Bedingungen angeben, die erfüllt sein müssen, damit ein Trace angezeigt wird. Mit der Filtersyntax können Sie definieren, wann Übereinstimmungen bestehen oder wann es sich um Präfix-Tests handelt. Bei allen Übereinstimmungen wird zwischen Groß- und Kleinschreibung unterschieden.

Filterübersicht

Trace-Filter bestehen aus einer Reihe von Vergleichen, die als Bedingungen bezeichnet werden. Traces müssen mit allen Bedingungen in dem ausgewählten Filter übereinstimmen. Der folgende Filter erkennt beispielsweise Traces mit einer Latenz von mindestens einer Sekunde, die einen Span mit dem Namen /modules.GetNumInstances enthalten:

+span:/modules.GetNumInstances latency:1s

Bei allen Stringvergleichen wird die Groß-/Kleinschreibung beachtet.

Boolesche Attribute

Verwenden Sie 0 für "false" und 1 für "true", um Werte für boolesche Attribute anzugeben. Beispiel:

Client:0

Sonderzeichen

Setzen Sie den Wert in doppelte Anführungszeichen ("), um nach einem Wert zu suchen, der ein Leerzeichen oder einen Doppelpunkt (:) enthält. Beispiel:

    label:"Notice: This value contains spaces and a colon"

Um in einem String in Anführungszeichen nach dem doppelten Anführungszeichen oder nach dem umgekehrten Schrägstrich (\) zu suchen, müssen Sie das Zeichen mit einem umgekehrten Schrägstrich maskieren. Beispiel:

    label:"Notice: This value contains spaces, a colon, a \"quote\", and a backslash (\\)"

Filtersyntax

In der folgenden Tabelle und an anderer Stelle auf dieser Seite bezieht sich NAME auf den Namen eines Felds, während sich VALUE auf den Wert eines Schlüssel/Wert-Paars bezieht. Die Strings _PREFIX und _EXACT sind visuelle Hinweise, ob ein Test ein Präfixtest oder eine genaue Übereinstimmung ist. root:[NAME_PREFIX] bedeutet beispielsweise, dass der Name des Haupt-Spans mit [NAME_PREFIX] beginnen muss.

In folgender Tabelle sind die Syntaxfilter aufgeführt, die in Cloud Trace verwendet werden:

Trace API- Anfragefilter auf der Seite Analyseberichte	Filter auf der Seite Trace Explorer
`root:[NAME_PREFIX]`	`RootSpan:[NAME_PREFIX]`
`+root:[NAME_EXACT]`	`RootSpan:+[NAME_EXACT]`
`span:[NAME_PREFIX]`	`SpanName:[NAME_PREFIX]`
`+span:[NAME_EXACT]`	`SpanName:+[NAME_EXACT]`
`[NAME_PREFIX]`	`RootSpan:[NAME_PREFIX]`
`label:[LABEL_KEY]`	`HasLabel:[LABEL_KEY]`
`[LABEL_KEY]: [VALUE_PREFIX]`	`[LABEL_KEY]:[VALUE_PREFIX]`^*
`+[LABEL_KEY]: [VALUE_EXACT]`	`[LABEL_KEY]:+[VALUE]`^*
`^[LABEL_KEY]: [VALUE_PREFIX]`	`[LABEL_KEY]:^[VALUE_PREFIX]`^*
`+^[LABEL_KEY]: [VALUE_EXACT]`	`[LABEL_KEY]:^+[VALUE_EXACT]`^{*, †}
`method:[VALUE_PREFIX]`	`Method:[VALUE_PREFIX]`
`latency:10ms`	`MinLatency:10ms`
`url:[VALUE_PREFIX]`	`URL:[VALUE_PREFIX]`

^* Verwenden Sie nicht die folgenden Trace-Keywords als Labelschlüssel: root, span, label, method, latency und url. Traces mit diesen Labelschlüsseln können nicht abgefragt werden.
^† Auf der Seite Trace Explorer wird die Annotation +^ in ^+ konvertiert, wenn Sie die Eingabetaste drücken.

Der Rest dieser Seite enthält eine Beschreibung für Filter zur Verwendung mit der Trace API und für den Anfragefilter auf der Seite Analyseberichte. Wenn Sie auf der Seite Trace Explorer das Feld Filter verwenden, können Sie anhand der Zuordnung in der vorherigen Tabelle einen entsprechenden Ausdruck erstellen.

Beispiele für Anfragefilter

Im Folgenden werden die Filterbegriffe beschrieben:

root:[NAME_PREFIX]

Der Name des Haupt-Spans in dem Trace muss mit [NAME_PREFIX] beginnen. Der folgende Filter stimmt beispielsweise mit einem Trace namens "/_ah/background" überein, aber nicht mit einem namens "/_ahx/background":

root:/_ah/

+root:[NAME]

Der Name des Haupt-Spans in dem Trace muss genau [NAME] sein. Beispiel:

+root:/_ah/background

[NAME_PREFIX]

Diese Syntax ist ein Kurzbefehl für root:[NAME_PREFIX].

+[NAME]

Diese Syntax ist ein Kurzbefehl für +root:[NAME].

span:[NAME_PREFIX]

Die Trace muss mindestens einen Span enthalten, dessen Name mit [NAME_PREFIX] beginnt. Beispiel:

span:/modules.

+span:[NAME]

Die Trace muss mindestens einen Span enthalten, dessen Name genau mit [NAME] übereinstimmt. Beispiel:

span:/modules.GetNumInstances

latency:[DURATION]

Die Gesamtlatenz in dem Trace muss größer oder gleich [DURATION] sein. Die Dauer wird als ganze Zahl gefolgt von einer Einheit angegeben: s für Sekunden, ms für Millisekunden oder ns für Nanosekunden. Wenn es kein Einheitenbezeichner gibt, sind die Einheiten Millisekunden. Zum Beispiel sind die folgenden vier Werte für die Dauer identisch:

 12s 12000ms 12000000ns 12000

label:[LABEL_KEY]

Der Trace muss genau den festgelegten Labelschlüssel enthalten. Der Wert des Labels (falls vorhanden) spielt keine Rolle. Beispiel:

label:/http/url

[LABEL_KEY]:[VALUE_PREFIX]

Der Trace muss genau den angegebenen Labelschlüssel enthalten und der Wert des Labels muss mit [VALUE_PREFIX] beginnen. Der folgende Begriff stimmt beispielsweise mit Traces überein, deren App Engine-Version mit "2017" beginnt.

g.co/gae/app/module_version:2017

+[LABEL_KEY]:[VALUE_EXACT]

Der Trace muss genau den für das Label angegebenen Schlüssel und Wert enthalten. Beispiel:

+g.co/gae/app/module_version:201750925t173233.387410594824284458

method:[VALUE_PREFIX]

Die Syntax ist ein Kurzbefehl für den Labeltest /http/method:[VALUE_PREFIX].

+method:[VALUE_EXACT]

Die Syntax ist ein Kurzbefehl für den Labeltest +/http/method:[VALUE_EXACT].

url:[VALUE_PREFIX]

Diese Syntax ist ein Kurzbefehl für den Labeltest /http/url:[VALUE_PREFIX].

+url:[VALUE_EXACT]

Die Syntax ist ein Kurzbefehl für den Labeltest +/http/url:[VALUE_EXACT].

Beispiele für Haupt-Span-Suchanfragen

Wenn Sie den Suchbegriff auf den Haupt-Span beschränken möchten, fügen Sie vor einem Suchbegriff und nach dem optionalen (+) ein (^) ein. Wenn Sie auf der Seite Trace Explorer im Feld Filter die Anmerkung +^ hinzufügen, wird diese bei Drücken der Eingabetaste in ^+ konvertiert.

Im Folgenden finden Sie einige Suchbegriffe, die nur auf Root-Spans beschränkt sind, und ihre Äquivalenzen:

^label:[LABEL_KEY]: Dies ist eine Haupt-Span-Suche nach label:[LABEL_KEY].
^[LABEL_KEY]:[VALUE_PREFIX]: Dies ist eine Haupt-Span-Suche nach [LABEL_KEY]:[VALUE_PREFIX].
+^[LABEL_KEY]:[VALUE]: Dies ist eine Haupt-Span-Suche nach +[LABEL_KEY]:[VALUE].
^method:[VALUE_PREFIX]: Dies ist eine Haupt-Span-Suche nach method:[VALUE_PREFIX].
+^method:[VALUE]: Dies ist eine Haupt-Span-Suche nach +method:[VALUE].
^url:[VALUE_PREFIX]: Dies ist eine Haupt-Span-Suche nach url:[VALUE_PREFIX].
+^url:[VALUE]: Dies ist eine Haupt-Span-Suche nach +url:[VALUE].
^span:[NAME_PREFIX]: Dies entspricht root:[NAME_PREFIX].
+^span:[NAME]: Dies entspricht +root:[NAME].

Durch Erstellen einer Abfrage mit gemischten Begriffen kann die Suche weiter angepasst werden. Beispiel:

    +^url:/main /images method:200

stimmt mit Traces überein, wenn das Label /http/url des Haupt-Spans genau „/main“ ist, dem Namen des Haupt-Spans das Präfix /images vorangestellt ist und jeder Span das Label /http/method mit dem Wert 200 hat.

Fehlerbehebung

Dieser Abschnitt enthält Inhalte zur Fehlerbehebung.

Beeinträchtigte Leistung

Wenn Ihr Trace-Filter komplex ist, dauert seine Ausführung länger und überschreitet möglicherweise das Zeitlimit. Vereinfachen Sie den Filter, um dies zu vermeiden.

Keine Ergebnisse

Prüfen Sie Folgendes, wenn Ihr Filter keine Traces zurückgibt:

Stellen Sie sicher, dass der Filter außer den Trennzeichen zwischen den Vergleichen keine weiteren Leerzeichen enthält.
Prüfen Sie die Groß-/Kleinschreibung und die Rechtschreibung aller Wörter im Filter. Wenn Sie beispielsweise einen Schlüsselbegriff wie method:GET falsch schreiben, wird der Filter als label:method:GET interpretiert, was mit keinem Trace übereinstimmt.
Wenn Sie die Filterbedingungen einzeln testen möchten, verwenden Sie den Trace Listen-Filter oder den API Explorer. Wenn eine der Bedingungen kein Ergebnis liefert, ist diese Bedingung möglicherweise das Problem.