使用篩選運算式

使用篩選器運算式來檢視特定要求、服務、兩個服務 (邊緣) 之間的連線或滿足條件的要求的追蹤對應或追蹤。X-Ray 提供篩選器運算式語言，可根據要求標頭、回應狀態和原始區段上的索引欄位中的資料篩選要求、服務和邊緣。

當您選擇要在 X-Ray 主控台中檢視的追蹤時段時，可能會得到比主控台顯示的更多結果。主控台會在右上角顯示已掃描的追蹤數目，但實際上可用的追蹤可能更多。您可以使用篩選器運算式將結果縮小為只要尋找的追蹤。

篩選條件表達式詳細資訊

當您在追蹤對應中選擇節點時，主控台會根據節點的服務名稱建構篩選器運算式，以及根據您的選取項目存在的錯誤類型。若要尋找顯示效能問題或與特定請求相關的追蹤，您可以調整主控台提供的表達式，或是自行建立。如果您使用 X-Ray 加入註釋SDK，您也可以根據註釋關鍵字的存在或鍵值進行篩選。

注意

如果您在追蹤對映中選擇相對時間範圍並選擇節點，主控台會將時間範圍轉換為絕對開始和結束時間。為了確保搜尋結果顯示節點的追蹤，並避免掃描未作用中節點的時間，時間範圍只包含節點傳送追蹤的時間。若要搜尋相對於目前的時間，您可以在追蹤頁面切換回相對時間範圍，並再次掃描。

如果可用結果超過主控台可以顯示的範圍，主控台會顯示相符的追蹤數和已掃描的追蹤數。顯示的百分比為所選時間範圍內已掃描的百分比。若要確保結果中可以顯示所有相符的追蹤，請進一步縮小篩選條件表達式，或選擇較短的時間範圍。

若要先取得最新的結果，主控台會從時間範圍結尾開始掃描，並倒退進行。如果有大量追蹤，但僅有少數結果，主控台會將時間範圍分成區塊並平行掃描。進度列會顯示已掃描的部分時間範圍。

搭配使用篩選條件表達式與群組

群組是一系列追蹤，為篩選條件表達式所定義。您可以使用群組產生其他服務圖表並提供 Amazon CloudWatch 指標。

群組可透過其名稱或 Amazon 資源名稱 (ARN) 識別，並包含篩選器運算式。此服務會比較傳入表達式的追蹤，並依序存放。

您可以在下拉式功能表，篩選條件表達式左側的搜尋列，建立或修改群組。

注意

如果服務驗證群組資格時發生錯誤，該群組即不會處理傳入的追蹤，且會記錄錯誤指標。

如需群組的詳細資訊，請參閱設定群組。

篩選條件表達式語法

篩選條件表達式可以包含「關鍵字」、一元或二元「運算子」以及用於比較的「值」。

keyword operator value

不同運算子適用於不同類型的關鍵字。例如，responsetime 是數字關鍵字，可相較於與數字相關的運算子。

範例 — 回應時間大於 5 秒的要求

responsetime > 5

您可以使用 AND 或 OR 運算子，將多個表達式結合成一個複合表達式。

範例 — 總持續時間為 5—8 秒的請求

duration >= 5 AND duration <= 8

簡單關鍵字和運算子只能發現追蹤層級的問題。如果下游發生錯誤，但已由您的應用程式處理而未傳回給使用者，搜尋 error 時就不會找到此錯誤。

若要尋找含有下游問題的追蹤，您可以使用複雜的關鍵字 service() 和 edge()。這些關鍵字可讓您將篩選條件表達式套用到所有下游節點、單一下游節點，或是兩個節點之間的邊緣。如需更高的精細程度，您可以依據 id() 函數類型來篩選服務和邊緣。

布林值關鍵字

布林值關鍵字值可為 true 或 false。使用這些關鍵字來尋找導致錯誤的追蹤。

布林值關鍵字

• ok— 響應狀態代碼為 2XX「成功」。

• error— 響應狀態代碼為 4XX 客戶端錯誤。

• throttle— 響應狀態代碼為 429 請求太多。

• fault— 回應狀態碼為 5XX 伺服器錯誤。

• partial— 請求具有不完整的區段。

• inferred— 請求推斷了區段。

• first— 元素是列舉清單的第一個。

• last— 元素是列舉清單的最後一個。

• remote— 根本原因實體是遠端的。

• root— 服務是追蹤的進入點或根區段。

布林值運算子可尋找指定索引鍵為 true 或 false 的區段。

布林值運算子

• 無 — 如果關鍵字為真，則表示式為真。

• !— 如果關鍵字為假，則表示式為 true。

• =，!=— 將關鍵字的值與字串true或比較false。這些運算子的作用與其他運算子相同，但更加明確。

範例 — 響應狀態為 2XX「確定」

ok

範例 — 響應狀態不是 2XX「確定」

!ok

範例 — 響應狀態不是 2XX「確定」

ok = false

範例 — 上次列舉的錯誤追蹤具有錯誤名稱「還原序列化」

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

範例 — 具有覆蓋範圍大於 0.7 且服務名稱為「追蹤」之遠端區段的要求

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

範例 — 具有推斷區段的請求，其中服務類型為 ": DynamoDB」AWS

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

範例 — 具有以「資料平面」為根名稱的區段的要求

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

數字關鍵字

使用數字關鍵字以搜尋含特定回應時間、持續時間或回應狀態的請求。

數字關鍵字

• responsetime— 伺服器傳送回應所花費的時間。

• duration— 總請求持續時間，包括所有下游呼叫。

• http.status— 響應狀態代碼。

• index— 元素在列舉清單中的位置。

• coverage— 根區段回應時間內實體回應時間的十進位百分比。僅適用於回應時間根本原因實體。

數字運算子

數字關鍵字使用標準的對等和比較運算子。

• =、!= — 關鍵字等於或不等於數字值。

• <、<=、>、>= — 關鍵字小於或大於數字值。

範例 — 響應狀態不是 200「確定」

http.status != 200

範例 — 請求總持續時間為 5—8 秒

duration >= 5 AND duration <= 8

範例 — 在 3 秒內成功完成的請求，包括所有下游呼叫

ok !partial duration <3

範例 — 具有大於 5 之索引的列舉清單實體

rootcause.fault.service { index > 5 }

範例 — 具有覆蓋範圍大於 0.8 的最後一個實體的請求

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

字串關鍵字

使用字串關鍵字來尋找要求標頭或特定使用者中包含特定文字的追蹤IDs。

字串關鍵字

• http.url— 請求URL.

• http.method— 請求方法。

• http.useragent— 要求使用者代理字串。

• http.clientip— 要求者的 IP 位址。

• user— 追蹤中任何區段上的使用者欄位值。

• name— 服務或例外的名稱。

• type— 服務類型。

• message— 例外狀況訊息。

• availabilityzone— 追蹤中任何區段上可用區域欄位的值。

• instance.id— 追蹤中任何區段上的執行個體 ID 欄位值。

• resource.arn— 追蹤中任何區段的資源ARN欄位值。

字串運算子可尋找等於或包含特定文字的值。您必須一律在引號中指定值。

字串運算子

• =、!= — 關鍵字等於或不等於數字值。

• CONTAINS— 關鍵字包含特定字串。

• BEGINSWITH, ENDSWITH — 關鍵字以特定字串開頭或結尾。

範例 -網址過濾器

http.url CONTAINS "/api/game/"

若要測試追蹤上是否存在欄位 (無論其值為何)，請檢查欄位是否包含空白字串。

範例 — 使用者篩選

與用戶一起查找所有跟踪IDs。

user CONTAINS ""

範例 — 選取具有錯誤根本原因的追蹤，其中包含名為「Auth」的服務

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

範例 — 選取具有回應時間根本原因的追蹤，其上一個服務具有 DynamoDB 類型

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

範例 — 選取具有錯誤根本原因的追蹤，其最後一個例外狀況會顯示「account_id 的存取遭拒：1234567890」

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

複雜關鍵字

使用複雜關鍵字以根據服務名稱、邊緣名稱或註釋值來尋找請求。若是服務和邊緣，您可以指定額外篩選條件表達式以套用到服務或邊緣。若是註釋，您可以使用布林值、數字或字串運算子，篩選含特定索引鍵的註釋值。

複雜關鍵字

• annotation[key]-帶有字段的註釋的值 key。 註釋的值可以是布林值、數字或字串，因此您可以使用這些類型的任何比較運算子。您可以將此關鍵字與 service or 關鍵edge字結合使用。包含點 (句號) 的註釋鍵必須以方括號 ([]) 括住。

• edge(source, destination) {filter}— 服務之間的連接 source 以及 destination。 選用的大括號可以包含套用至此連線區段的篩選器運算式。

• group.name / group.arn— 群組篩選運算式的值，依群組名稱或群組參照ARN。

• json— JSON 根本原因物件。如需透過程式設計方式建立JSON實體的步驟，請參閱從 AWS X-Ray

• service(name) {filter}— 名稱服務 name。 選用的大括號可以包含套用至服務建立之區段的篩選器運算式。

使用 service 關鍵字來尋找追蹤對應上某個節點的要求追蹤。

複雜的關鍵字運算子會尋找已設定或未設定指定索引鍵的區段。

複雜關鍵字運算

• 無 — 如果已設定關鍵字，則表示式為 true。如果關鍵字是布爾類型，它將評估為布爾值。

• !— 如果未設定關鍵字，則表示式為 true。如果關鍵字是布爾類型，它將評估為布爾值。

• =，!=— 比較關鍵字的值。

• edge(source, destination) {filter}— 服務之間的連接 source 以及 destination。 選用的大括號可以包含套用至此連線區段的篩選器運算式。

• annotation[key]-帶有字段的註釋的值 key。 註釋的值可以是布林值、數字或字串，因此您可以使用這些類型的任何比較運算子。您可以將此關鍵字與 service or 關鍵edge字結合使用。

• json— JSON 根本原因物件。如需透過程式設計方式建立JSON實體的步驟，請參閱從 AWS X-Ray

使用 service 關鍵字來尋找追蹤對應上某個節點的要求追蹤。

範例 — 服務過濾器

包含對 api.example.com 的呼叫且發生故障 (500 系列錯誤) 的請求。

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

您可以排除服務名稱，以將篩選條件表達式套用到服務地圖中的所有節點。

範例 — 服務過濾器

在追蹤對應上的任何位置造成錯誤的要求。

service() { fault }

邊緣關鍵字可將篩選條件表達式套用到兩個節點之間的連線。

範例 — 邊緣濾鏡

api.example.com 服務對 backend.example.com 發出呼叫但因錯誤而失敗的請求。

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

您也可以搭配使用 ! 運算子與服務和邊緣關鍵字，以排除其他篩選條件表達式結果的服務或邊緣。

範例 — 服務和請求過濾器

請求的URL開頭http://api.example.com/和包含，/v2/但未到達名為的服務api.example.com。

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

範例 — 服務和響應時間過濾器

尋找http url已設定且回應時間大於 2 秒的追蹤。

http.url AND responseTime > 2

對於註釋，您可以調用設置的所有跟踪，或使用對應於值類型的比較運算符。annotation[key]

範例 -帶有字符串值的註釋

含名稱為 gameid、字串值為 "817DL6VO" 之註釋的請求。

annotation[gameid] = "817DL6VO"

範例 — 註釋被設置

具有名為 age set 之註釋的請求。

annotation[age]

範例 — 未設定註解

沒有註釋命名為 age set 的請求。

!annotation[age]

範例 -帶有數字值的註釋

含註釋存留期且數值大於 29 的請求。

annotation[age] > 29

範例 -與服務或邊緣組合的註釋

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

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

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

範例 — 與用戶組

追蹤符合high_response_time群組篩選條件的要求 (例如responseTime > 3)，且使用者名為 Alice。

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

範例 — JSON 具有根本原因實體

有相符根本原因實體的請求。

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

id 函數

當您將服務名稱提供給 service 或 edge 關鍵字時，您可取得具有該名稱之所有節點的結果。如需更精確的篩選，除了名稱之外，您還可以使用 id 函數來指定服務類型，以區分名稱相同的節點。

檢視監視帳戶中多個帳戶的追蹤時，請使用此account.id函數來指定服務的特定帳戶。

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

您可以使用 id 函數來代替服務和邊緣篩選條件中的服務名稱。

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 函數會在追蹤對映中產生兩個節點；一個用於函數叫用，另一個用於 Lambda 服務。這兩個節點的名稱相同，但類型不同。標準的服務篩選條件可尋找這兩種追蹤。

範例 — 服務過濾器

包含任何名為 random-name 服務上的錯誤的請求。

service("function-name") { error }

使用 id 函數來縮小搜尋範圍至函數本身的錯誤，而不含服務的錯誤。

範例 — 具有 id 功能的服務過濾器

包含名為 random-name、類型為 AWS::Lambda::Function 服務上的錯誤的請求。

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

若要依據類型來搜尋節點，您也可以完全排除名稱。

範例 — 具有 id 功能和服務類型的服務過濾器

包含類型為 AWS::Lambda::Function 服務上的錯誤的請求。

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

若要搜尋特定節點 AWS 帳戶，請指定帳號 ID。

範例 — 具有 ID 功能和帳戶 ID 的服務過濾器

在特定帳戶 ID 中包含服務的要求AWS::Lambda::Function。

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