Verwenden von Filterausdrücken

Verwenden Sie Filterausdrücke, um eine Trace-Map oder Traces für eine bestimmte Anfrage, einen bestimmten Dienst, eine Verbindung zwischen zwei Diensten (ein Edge) oder Anfragen, die eine Bedingung erfüllen, anzuzeigen. X-Ray bietet eine Sprache für Filterausdrücke zum Filtern von Anfragen, Diensten und Kanten auf der Grundlage von Daten in Anforderungsheadern, Antwortstatus und indizierten Feldern in den ursprünglichen Segmenten.

Wenn Sie einen Zeitraum für die Anzeige von Traces in der X-Ray-Konsole auswählen, erhalten Sie möglicherweise mehr Ergebnisse, als die Konsole anzeigen kann. In der rechten oberen Ecke der Konsole wird die Anzahl der gescannten Ablaufverfolgungen angezeigt und Sie können ablesen, ob weitere Ablaufverfolgungen verfügbar sind. Sie können einen Filterausdruck verwenden, um die Ergebnisse auf die Spuren einzugrenzen, nach denen Sie suchen möchten.

Details zu Filterausdrücken

Wenn Sie einen Knoten in der Trace-Map auswählen, erstellt die Konsole einen Filterausdruck, der auf dem Dienstnamen des Knotens und den auf Ihrer Auswahl beruhenden Fehlertypen basiert. Um Ablaufverfolgungen zu finden, die Leistungsprobleme zeigen oder zu bestimmten Anfragen gehören, können Sie den von der Konsole bereitgestellten Ausdruck anpassen oder einen eigenen erstellen. Wenn Sie Anmerkungen mit dem X-Ray hinzufügenSDK, können Sie auch nach dem Vorhandensein eines Kommentarschlüssels oder dem Wert eines Schlüssels filtern.

Anmerkung

Wenn Sie in der Trace-Map einen relativen Zeitraum und dann einen Knoten auswählen, rechnet die Konsole den Zeitraum in eine absolute Start- und Endzeit um. Um sicherzustellen, dass die Ablaufverfolgungen für den Knoten in den Suchergebnissen angezeigt werden, und um das Scannen von Zeiträumen zu vermeiden, in denen der Knoten nicht aktiv war, werden nur Zeiten in den Zeitraum einbezogen, zu denen der Knoten Ablaufverfolgungen gesendet hat. Um relativ zur aktuellen Zeit zu suchen, können Sie wieder zum relativen Zeitraum auf der Seite der Ablaufverfolgungen wechseln und einen erneuten Scan durchführen.

Wenn immer noch mehr Ergebnisse vorliegen, als in der Konsole angezeigt werden können, gibt die Konsole die Anzahl der Ablaufverfolgungen an, die die Kriterien erfüllt haben, sowie die Anzahl der gescannten Ablaufverfolgungen. Der angezeigte Prozentsatz entspricht dem Prozentsatz des ausgewählten Zeitraums, der gescannt wurde. Um sicherzustellen, dass alle passenden Ablaufverfolgungen in den Ergebnissen angezeigt werden, grenzen Sie Ihren Filterausdruck weiter ein oder wählen einen kürzeren Zeitraum aus.

Die Konsole beginnt den Scan am Ende des Zeitraums und arbeitet sich nach vorne durch, um Ihnen die aktuellsten Ergebnisse zuerst anzuzeigen. Wenn viele Ablaufverfolgungen vorliegen, aber nur wenige Ergebnisse, teilt die Konsole den Zeitraum in Abschnitte ein und scannt diese parallel. Der Fortschrittsbalken zeigt die Abschnitte des Zeitraums an, die gescannt wurden.

Verwenden von Filterausdrücken mit Gruppen

Gruppen sind eine Sammlung von Ablaufverfolgungen, die durch einen Filterausdruck definiert sind. Sie können Gruppen verwenden, um zusätzliche Servicegraphen zu erstellen und CloudWatch Amazon-Metriken bereitzustellen.

Gruppen werden durch ihren Namen oder einen Amazon-Ressourcennamen (ARN) identifiziert und enthalten einen Filterausdruck. Der Service vergleicht eingehende Ablaufverfolgungen mit dem Ausdruck und speichert sie entsprechend.

Sie können Gruppen mit dem Dropdown-Menü links neben der Suchleiste des Filterausdrucks erstellen und ändern.

Anmerkung

Wenn der Service einen Fehler beim Qualifizieren einer Gruppe feststellt, ist diese Gruppe nicht mehr in der Verarbeitung eingehender Ablaufverfolgungen enthalten und es wird eine Fehlermetrik aufgezeichnet.

Weitere Informationen zu Gruppen finden Sie unterKonfigurieren von Gruppen.

Syntax für Filterausdrücke

Filterausdrücke können ein Schlüsselwort, einen unären oder binären Operator und einen Wert für den Vergleich enthalten.

keyword operator value

Für verschiedene Arten von Schlüsselwörtern sich unterschiedliche Operatoren erhältlich. Beispielsweise ist responsetime ein Zahlenschlüsselwort, das mit auf Zahlen bezüglichen Operatoren verglichen werden kann.

Beispiel — Anfragen, bei denen die Antwortzeit mehr als 5 Sekunden betrug

responsetime > 5

Sie können mehrere Ausdrücke zu einem zusammengesetzten Ausdruck verbinden, indem Sie die Operatoren AND oder OR verwenden.

Beispiel — Anfragen mit einer Gesamtdauer von 5—8 Sekunden

duration >= 5 AND duration <= 8

Einfache Schlüsselwörter und Operatoren finden Probleme nur auf der Ebene der Ablaufverfolgungen. Wenn ein Fehler dahinter auftritt, von Ihrer Anwendung jedoch berücksichtigt und nicht an den Benutzer zurückgegeben wird, findet eine Suche nach error diesen Fehler nicht.

Zum Finden von Ablaufverfolgungen mit nachgeordneten Fehlern können Sie komplexe Schlüsselwörter service() und edge() verwenden. Diese Schlüsselwörter ermöglichen die Anwendung eines Filterausdrucks auf alle nachgeordneten Knoten, einen einzelnen nachgeordneten Knoten oder eine Edge zwischen zwei Knoten. Für mehr Granularität können Sie Services und Edges mit der id()-Funktion nach Typ filtern.

Boolesche Schlüsselwörter

Boolesche Schlüsselwortwerte sind entweder „true“ oder „false“. Verwenden Sie diese Schlüsselwörter, um Ablaufverfolgungen zu finden, die zu Fehlern geführt haben.

Boolesche Schlüsselwörter

• ok— Der Statuscode der Antwort lautete 2XX Success.

• error— Der Antwortstatuscode lautete 4XX Client Error.

• throttle— Der Antwortstatuscode lautete 429 Too Many Requests.

• fault— Der Antwortstatuscode lautete 5XX Server Error.

• partial— Die Anfrage enthält unvollständige Segmente.

• inferred— Die Anfrage hat abgeleitete Segmente.

• first— Element ist das erste Element einer aufgezählten Liste.

• last— Element ist das letzte Element einer Aufzählungsliste.

• remote— Die Ursachenentität ist entfernt.

• root— Service ist der Einstiegspunkt oder das Stammsegment einer Ablaufverfolgung.

Boolesche Operatoren finden Segmente, bei denen der angegebene Schlüssel true oder false ist.

Boolesche Operatoren

• none — Der Ausdruck ist wahr, wenn das Schlüsselwort wahr ist.

• !— Der Ausdruck ist wahr, wenn das Schlüsselwort falsch ist.

• =, != — Vergleicht den Wert des Schlüsselworts mit der Zeichenfolge true oderfalse. Diese Operatoren verhalten sich genauso wie die anderen Operatoren, sind jedoch expliziter.

Beispiel — Der Antwortstatus ist 2XX OK

ok

Beispiel — der Antwortstatus ist nicht 2XX OK

!ok

Beispiel — der Antwortstatus ist nicht 2XX OK

ok = false

Beispiel — Der letzte aufgezählte Fehler-Trace hat den Fehlernamen „deserialize“

rootcause.fault.entity { last and name = "deserialize" }

Beispiel — Anfragen mit entfernten Segmenten, bei denen die Abdeckung größer als 0,7 ist und der Dienstname „traces“ lautet

rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }

Beispiel — Anfragen mit abgeleiteten Segmenten, bei denen der Diensttyp „:DynamoDB“ AWS ist

rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }

Beispiel — Anfragen, die ein Segment mit dem Namen „Datenebene“ als Wurzel haben

service("data-plane") {root = true and fault = true}

Zahlenschlüsselwörter

Verwenden Sie Zahlenschlüsselwörter, um nach Anforderungen mit einer bestimmten Reaktionszeit, Dauer oder einem bestimmten Reaktionsstatus zu suchen.

Zahlenschlüsselwörter

• responsetime— Zeit, die der Server benötigt hat, um eine Antwort zu senden.

• duration— Gesamtdauer der Anfrage, einschließlich aller Downstream-Aufrufe.

• http.status— Statuscode der Antwort.

• index— Position eines Elements in einer aufgezählten Liste.

• coverage— Dezimaler Prozentsatz der Antwortzeit der Entität im Vergleich zur Antwortzeit des Stammsegments. Gilt nur für die Reaktionszeit der Ursachenentitäten.

Zahlenoperatoren

Zahlenschlüsselwörter verwenden Standard-Operatoren für Gleichheit und Vergleich.

• =, != — Das Schlüsselwort ist gleich oder ungleich einem Zahlenwert.

• <,<=,>, >= — Das Schlüsselwort ist kleiner oder größer als ein Zahlenwert.

Beispiel — Der Antwortstatus ist nicht 200 OK

http.status != 200

Beispiel — Anfrage, bei der die Gesamtdauer 5—8 Sekunden betrug

duration >= 5 AND duration <= 8

Beispiel — Anfragen, die in weniger als 3 Sekunden erfolgreich abgeschlossen wurden, einschließlich aller Downstream-Aufrufe

ok !partial duration <3

Beispiel — Entität mit einer aufgezählten Liste, deren Index größer als 5 ist

rootcause.fault.service { index > 5 }

Beispiel — Anfragen, bei denen die letzte Entität, deren Abdeckung größer als 0,8 ist

rootcause.responsetime.entity { last and coverage > 0.8 }

Zeichenfolgen-Schlüsselwörter

Verwenden Sie String-Schlüsselwörter, um Traces mit einem bestimmten Text in den Headern der Anfrage oder nach einem bestimmten Benutzer IDs zu finden.

Zeichenfolgen-Schlüsselwörter

• http.url— AnfrageURL.

• http.method— Methode der Anfrage.

• http.useragent— User-Agent-Zeichenfolge anfordern.

• http.clientip— Die IP-Adresse des Anforderers.

• user— Wert des Benutzerfeldes in einem beliebigen Segment im Trace.

• name— Der Name eines Dienstes oder einer Ausnahme.

• type— Art der Dienstleistung.

• message— Ausnahmemeldung.

• availabilityzone— Wert des AvailabilityZone-Felds für ein beliebiges Segment im Trace.

• instance.id— Wert des Instanz-ID-Felds für ein beliebiges Segment im Trace.

• resource.arn— Wert des ARN Ressourcenfeldes in einem beliebigen Segment im Trace.

Zeichenfolgenoperatoren finden Werte, die identisch mit bestimmtem Text sind oder diesen enthalten. Werte müssen stets in Anführungszeichen angegeben werden.

Zeichenfolgenoperatoren

• =, != — Das Schlüsselwort ist gleich oder ungleich einem Zahlenwert.

• CONTAINS— Das Schlüsselwort enthält eine bestimmte Zeichenfolge.

• BEGINSWITH, ENDSWITH — Das Schlüsselwort beginnt oder endet mit einer bestimmten Zeichenfolge.

Beispiel — http.url-Filter

http.url CONTAINS "/api/game/"

Um zu testen, ob ein Feld in einer Ablaufverfolgung vorhanden ist (unabhängig von seinem Wert), prüfen Sie, ob es die leere Zeichenfolge enthält.

Beispiel — Benutzerfilter

Finde alle Spuren mit dem BenutzerIDs.

user CONTAINS ""

Beispiel — Wählen Sie Traces mit einer Fehlerursache aus, zu der auch ein Dienst mit dem Namen „Auth“ gehört

rootcause.fault.service { name = "Auth" }

Beispiel — wählt Traces mit einer Hauptursache für die Antwortzeit aus, deren letzter Service den Typ DynamoDB hat

rootcause.responsetime.service { last and type = "AWS::DynamoDB" }

Beispiel — wählt Traces mit einer Fehlerursache aus, deren letzte Ausnahme die Meldung „Zugriff verweigert für account_id: 1234567890" enthält

rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890" 

Komplexe Schlüsselwörter

Verwenden Sie komplexe Schlüsselwörter, um Anfragen anhand des Servicenamens, des Edge-Namens oder des Anmerkungswerts zu finden. Für Services und Edges können Sie einen zusätzlichen Filterausdruck angeben, der sich auf den Service oder die Edge bezieht. Für Anmerkungen können Sie nach dem Wert einer Anmerkung mit einem bestimmten Schlüssel filtern und dafür boolesche Werte, Zahlen oder Zeichenfolgenoperatoren verwenden.

Komplexe Schlüsselwörter

• annotation[key]— Wert einer Anmerkung mit Feld key. Der Wert einer Anmerkung kann ein boolescher Wert, eine Zahl oder eine Zeichenfolge sein, sodass Sie jeden der Vergleichsoperatoren dieser Typen verwenden können. Sie können dieses Schlüsselwort in Kombination mit dem Schlüsselwort service or edge verwenden. Ein Kommentarschlüssel, der Punkte (Punkte) enthält, muss in eckige Klammern ([]) eingeschlossen werden.

• edge(source, destination) {filter}— Verbindung zwischen Diensten source and destination. Optionale geschweifte Klammern können einen Filterausdruck enthalten, der für Segmente in dieser Verbindung gilt.

• group.name / group.arn— Der Wert des Filterausdrucks einer Gruppe, auf den durch den Gruppennamen oder die Gruppe verwiesen wird. ARN

• json— JSON Ursachenobjekt. Schritte zum programmgesteuerten Erstellen von JSON Entitäten finden Sie unter Daten aus AWS X-Ray abrufen.

• service(name) {filter}— Dienst mit Namen name. Optionale geschweifte Klammern können einen Filterausdruck enthalten, der für vom Service erstellte Segmente gilt.

Verwenden Sie das Schlüsselwort service, um Traces für Anfragen zu finden, die einen bestimmten Knoten auf Ihrer Trace-Map erreichen.

Komplexe Schlüsselwort-Operatoren finden Segmente, in denen der angegebene Schlüssel gesetzt wurde oder nicht.

Komplexe Schlüsselwort-Operatoren

• none — Der Ausdruck ist wahr, wenn das Schlüsselwort gesetzt ist. Wenn das Schlüsselwort vom Typ Boolean ist, wird es als boolescher Wert ausgewertet.

• !— Der Ausdruck ist wahr, wenn das Schlüsselwort nicht gesetzt ist. Wenn das Schlüsselwort vom Typ Boolean ist, wird es als boolescher Wert ausgewertet.

• =, != — Vergleicht den Wert des Schlüsselworts.

• edge(source, destination) {filter}— Verbindung zwischen Diensten source and destination. Optionale geschweifte Klammern können einen Filterausdruck enthalten, der für Segmente in dieser Verbindung gilt.

• annotation[key]— Wert einer Anmerkung mit Feld key. Der Wert einer Anmerkung kann ein boolescher Wert, eine Zahl oder eine Zeichenfolge sein, sodass Sie jeden der Vergleichsoperatoren dieser Typen verwenden können. Sie können dieses Schlüsselwort in Kombination mit dem Schlüsselwort service or edge verwenden.

• json— JSON Ursachenobjekt. Schritte zum programmgesteuerten Erstellen von JSON Entitäten finden Sie unter Daten aus AWS X-Ray abrufen.

Verwenden Sie das Schlüsselwort service, um Traces für Anfragen zu finden, die einen bestimmten Knoten auf Ihrer Trace-Map treffen.

Beispiel — Servicefilter

Anforderungen mit einem Aufruf an api.example.com mit einem Fehler (Fehler der Serie 500).

service("api.example.com") { fault }

Sie können den Servicenahmen ausschließen, um einen Filterausdruck auf alle Knoten in Ihrer Service-Übersicht anzuwenden.

Beispiel — Servicefilter

Anfragen, die an einer beliebigen Stelle auf Ihrer Trace-Map einen Fehler verursacht haben.

service() { fault }

Das Edge-Schlüsselwort wendet einen Filterausdruck auf eine Verbindung zwischen zwei Knoten an.

Beispiel — Kantenfilter

Anforderung, bei der der Service api.example.com einen Aufruf an backend.example.com vorgenommen hat, der mit einem Fehler fehlgeschlagen ist.

edge("api.example.com", "backend.example.com") { error }

Sie können auch den !-Operator mit Service- und Edge-Schlüsselwörtern verwenden, um einen Service oder eine Edge aus den Ergebnissen eines anderen Filterausdrucks auszuschließen.

Beispiel — Service- und Anfragefilter

Anfrage, bei der der mit einem genannten Dienst URL beginnt http://api.example.com/ und diesen enthält, ihn /v2/ aber nicht erreichtapi.example.com.

http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")

Beispiel — Filter für Service und Antwortzeit

Findet Spuren, bei denen der Wert eingestellt http url ist und die Reaktionszeit länger als 2 Sekunden ist.

http.url AND responseTime > 2

Für Anmerkungen können Sie alle Traces aufrufen, bei denen der Wert gesetzt annotation[key] ist, oder Sie können die Vergleichsoperatoren verwenden, die dem Wertetyp entsprechen.

Beispiel — Anmerkung mit Zeichenkettenwert

Anforderungen mit einer Anmerkung mit dem Namen gameid und dem Zeichenfolgenwert "817DL6VO".

annotation[gameid] = "817DL6VO"

Beispiel — Anmerkung ist gesetzt

Anfragen mit einer Anmerkung namens age set.

annotation[age]

Beispiel — Anmerkung ist nicht gesetzt

Anfragen ohne eine Anmerkung namens age set.

!annotation[age]

Beispiel — Anmerkung mit Zahlenwert

Anforderungen mit einer Anmerkung mit einem numerischen Wert größer als 29.

annotation[age] > 29

Beispiel — Anmerkung in Kombination mit Service oder Edge

service { annotation[request.id] = "917DL6VO" }

edge { source.annotation[request.id] = "916DL6VO" }

edge { destination.annotation[request.id] = "918DL6VO" }

Beispiel — Gruppe mit Benutzer

Anfragen, bei denen Traces auf den high_response_time Gruppenfilter treffen (z. B.responseTime > 3) und der Benutzer den Namen Alice hat.

group.name = "high_response_time" AND user = "alice"

Beispiel — JSON mit der Ursachenentität

Anforderungen mit übereinstimmenden Ursachenentitäten.

rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

id-Funktion

Wenn Sie einen Service-Namen für die Schlüsselwörter service oder edge bereitstellen, erhalten Sie Ergebnisse für alle Knoten mit diesem Namen. Für eine präzisere Filterung können Sie mit der id-Funktion zusätzlich zu einem Namen einen Servicetyp angeben, um zwischen Knoten mit demselben Namen zu differenzieren.

Verwenden Sie die account.id Funktion, um ein bestimmtes Konto für den Dienst anzugeben, wenn Sie Traces von mehreren Konten in einem Monitoring-Konto anzeigen möchten.

id(name: "service-name", type:"service::type", account.id:"account-ID")

Sie können die id-Funktion anstelle eines Service-Namens in Service- und Edge-Filtern verwenden.

service(id(name: "service-name", type:"service::type")) { filter }

edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }

AWS Lambda Funktionen führen beispielsweise zu zwei Knoten in der Trace-Map; einer für den Funktionsaufruf und einer für den Lambda-Service. Die zwei Knoten haben denselben Namen, aber unterschiedliche Arten. Ein Standard-Servicefilter findet Ablaufnachverfolgungen für beide.

Beispiel — Dienstfilter

Anforderungen, die einen Fehler bei einem Service mit dem Namen random-name enthalten.

service("function-name") { error }

Verwenden Sie die id-Funktion zur Eingrenzung der Suche auf Fehler bei der Funktion selbst, unter Ausschluss von Fehlern vom Service.

Beispiel — Servicefilter mit ID-Funktion

Anforderungen, die einen Fehler bei einem Service mit dem Namen random-name und dem Typ AWS::Lambda::Function enthalten.

service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }

Um Knoten nach Typ zu suchen, können Sie den Namen auch vollständig ausschließen.

Beispiel — Servicefilter mit ID-Funktion und Servicetyp

Anforderungen, die einen Fehler bei einem Service des Typs AWS::Lambda::Function enthalten.

service(id(type: "AWS::Lambda::Function")) { error }

Um nach Knoten für einen bestimmten Knoten zu suchen AWS-Konto, geben Sie eine Konto-ID an.

Beispiel — Servicefilter mit ID-Funktion und Konto-ID

Anfragen, die einen Dienst innerhalb einer bestimmten Konto-ID beinhaltenAWS::Lambda::Function.

service(id(account.id: "account-id"))