本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用篩選條件表達式
使用*篩選條件表達式*來檢視特定請求、服務、兩個服務之間的連線 （邊緣） 或滿足條件之請求的追蹤映射或追蹤。X-Ray 提供篩選條件表達式語言，可根據請求標頭中的資料、回應狀態和原始區段上的索引欄位來篩選請求、服務和邊緣。
當您選擇要在 X-Ray 主控台中檢視的追蹤期間時，可能會得到比主控台可顯示更多的結果。主控台會在右上角顯示已掃描的追蹤數目，但實際上可用的追蹤可能更多。您可以使用篩選條件表達式，將結果縮小為僅您要尋找的追蹤。
**Topics**
+ [篩選條件表達式詳細資訊](#xray-console-filters-details)
+ [搭配使用篩選條件表達式與群組](#groups)
+ [篩選條件表達式語法](#console-filters-syntax)
+ [布林值關鍵字](#console-filters-boolean)
+ [數字關鍵字](#console-filters-number)
+ [字串關鍵字](#console-filters-string)
+ [複雜關鍵字](#console-filters-complex)
+ [id 函數](#console-filters-functions)
## 篩選條件表達式詳細資訊
當您[在追蹤映射中選擇節點](xray-console-servicemap.md)時，主控台會根據節點的服務名稱，以及根據您的選擇存在的錯誤類型，建構篩選條件表達式。若要尋找顯示效能問題或與特定請求相關的追蹤，您可以調整主控台提供的表達式，或是自行建立。如果您使用 X-Ray SDK 新增註釋，您也可以根據註釋索引鍵的存在或索引鍵的值進行篩選。
**注意**
如果您在追蹤映射中選擇相對時間範圍並選擇節點，主控台會將時間範圍轉換為絕對開始和結束時間。為了確保搜尋結果顯示節點的追蹤，並避免掃描未作用中節點的時間，時間範圍只包含節點傳送追蹤的時間。若要搜尋相對於目前的時間，您可以在追蹤頁面切換回相對時間範圍，並再次掃描。
如果可用結果超過主控台可以顯示的範圍，主控台會顯示相符的追蹤數和已掃描的追蹤數。顯示的百分比為所選時間範圍內已掃描的百分比。若要確保結果中可以顯示所有相符的追蹤，請進一步縮小篩選條件表達式，或選擇較短的時間範圍。
若要先取得最新的結果，主控台會從時間範圍結尾開始掃描，並倒退進行。如果有大量追蹤，但僅有少數結果，主控台會將時間範圍分成區塊並平行掃描。進度列會顯示已掃描的部分時間範圍。
![\[Progress bar showing 52% of time range scanned, with 49 matching traces found.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-tracescan-parallel.png)
## 搭配使用篩選條件表達式與群組
群組是由篩選條件表達式定義的追蹤集合。您可以使用 群組來產生額外的服務圖表，並提供 Amazon CloudWatch 指標。
群組會根據名稱或 Amazon Resource Name (ARN) 進行識別，且包含篩選條件表達式。此服務會比較傳入表達式的追蹤，並依序存放。
您可以在下拉式功能表，篩選條件表達式左側的搜尋列，建立或修改群組。
**注意**
如果服務驗證群組資格時發生錯誤，該群組即不會處理傳入的追蹤，且會記錄錯誤指標。
如需 群組的詳細資訊，請參閱 [設定 群組](xray-console-groups.md)。
## 篩選條件表達式語法
篩選條件表達式可以包含「關鍵字」**、一元或二元「運算子」**以及用於比較的「值」**。
```
keyword operator value
```
不同運算子適用於不同類型的關鍵字。例如，`responsetime` 是數字關鍵字，可相較於與數字相關的運算子。
**Example – 回應時間大於 5 秒的請求**
```
responsetime > 5
```
您可以使用 `AND` 或 `OR` 運算子，將多個表達式結合成一個複合表達式。
**Example – 總持續時間為 5-8 秒的請求**
```
duration >= 5 AND duration <= 8
```
簡單關鍵字和運算子只能發現追蹤層級的問題。如果下游發生錯誤，但已由您的應用程式處理而未傳回給使用者，搜尋 `error` 時就不會找到此錯誤。
若要尋找含有下游問題的追蹤，您可以使用[複雜的關鍵字](#console-filters-complex) `service()` 和 `edge()`。這些關鍵字可讓您將篩選條件表達式套用到所有下游節點、單一下游節點，或是兩個節點之間的邊緣。如需更高的精細程度，您可以依據 [id() 函數](#console-filters-functions)類型來篩選服務和邊緣。
## 布林值關鍵字
布林值關鍵字值可為 true 或 false。使用這些關鍵字來尋找導致錯誤的追蹤。
**布林值關鍵字**
+ `ok` – 回應狀態碼為 2XX 成功。
+ `error` – 回應狀態碼為 4XX 用戶端錯誤。
+ `throttle` – 回應狀態碼為 429 太多請求。
+ `fault` – 回應狀態碼為 5XX 伺服器錯誤。
+ `partial` – 請求的區段不完整。
+ `inferred` – 請求已推斷客群。
+ `first` – Element 是列舉清單的第一個。
+ `last` – Element 是列舉清單的最後一個。
+ `remote` – 根本原因實體為遠端。
+ `root` – 服務是追蹤的進入點或根區段。
布林值運算子可尋找指定索引鍵為 `true` 或 `false` 的區段。
**布林值運算子**
+ none – 如果關鍵字為 true，則表達式為 true。
+ `!` – 如果關鍵字為 false，表示表達式為 true。
+ `=`，`!=` – 將關鍵字的值與字串`true`或 進行比較`false`。這些運算子的作用與其他運算子相同，但更加明確。
**Example – 回應狀態為 2XX OK**
```
ok
```
**Example – 回應狀態不是 2XX OK**
```
!ok
```
**Example – 回應狀態不是 2XX OK**
```
ok = false
```
**Example – 最後一個列舉的錯誤追蹤具有錯誤名稱 "deserialize"**
```
rootcause.fault.entity { last and name = "deserialize" }
```
**Example – 具有遠端區段的請求，涵蓋範圍大於 0.7 且服務名稱為 "traces"**
```
rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }
```
**Example – 具有推斷客群的請求，其中服務類型為「AWS：DynamoDB」**
```
rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }
```
**Example – 具有名為 "data-plane" 作為根的客群的請求**
```
service("data-plane") {root = true and fault = true}
```
## 數字關鍵字
使用數字關鍵字以搜尋含特定回應時間、持續時間或回應狀態的請求。
**數字關鍵字**
+ `responsetime` – 伺服器傳送回應所花費的時間。
+ `duration` – 請求總持續時間，包括所有下游呼叫。
+ `http.status` – 回應狀態碼。
+ `index` – 列舉清單中 元素的位置。
+ `coverage` – 實體回應時間相對於根區段回應時間的十進位百分比。僅適用於回應時間根本原因實體。
**數字運算子**
數字關鍵字使用標準的對等和比較運算子。
+ `=`，`!=` – 關鍵字等於或不等於數值。
+ `<`、`<=``>`、 `>=`- 關鍵字小於或等於數值。
**Example – 回應狀態不是 200 OK**
```
http.status != 200
```
**Example – 總持續時間為 5-8 秒的請求**
```
duration >= 5 AND duration <= 8
```
**Example – 在不到 3 秒內成功完成的請求，包括所有下游呼叫**
```
ok !partial duration <3
```
**Example – 索引大於 5 的列舉清單實體**
```
rootcause.fault.service { index > 5 }
```
**Example – 涵蓋範圍大於 0.8 的最後一個實體的請求**
```
rootcause.responsetime.entity { last and coverage > 0.8 }
```
## 字串關鍵字
使用字串關鍵字以尋找請求標頭中含特定文字或特定使用者 ID 的追蹤。
**字串關鍵字**
+ `http.url` – 請求 URL。
+ `http.method` – 請求方法。
+ `http.useragent` – 請求使用者代理程式字串。
+ `http.clientip` – 申請者的 IP 地址。
+ `user` – 追蹤中任何區段的使用者欄位值。
+ `name` – 服務或例外狀況的名稱。
+ `type` – 服務類型。
+ `message` – 例外狀況訊息。
+ `availabilityzone` – 追蹤中任何區段的 availabilityzone 欄位值。
+ `instance.id` – 追蹤中任何區段上執行個體 ID 欄位的值。
+ `resource.arn` – 追蹤中任何區段上資源 ARN 欄位的值。
字串運算子可尋找等於或包含特定文字的值。您必須一律在引號中指定值。
**字串運算子**
+ `=`，`!=` – 關鍵字等於或不等於數值。
+ `CONTAINS` – 關鍵字包含特定字串。
+ `BEGINSWITH` ， `ENDSWITH` – 關鍵字以特定字串開頭或結尾。
**Example – http.url 篩選條件**
```
http.url CONTAINS "/api/game/"
```
若要測試追蹤上是否存在欄位 (無論其值為何)，請檢查欄位是否包含空白字串。
**Example – 使用者篩選條件**
尋找所有含使用者 ID 的追蹤。
```
user CONTAINS ""
```
**Example – 選取具有故障根本原因的追蹤，其中包含名為 "Auth" 的服務**
```
rootcause.fault.service { name = "Auth" }
```
**Example – 選取具有回應時間根本原因的追蹤，其上次服務具有 DynamoDB 類型**
```
rootcause.responsetime.service { last and type = "AWS::DynamoDB" }
```
**Example – 選取具有故障根本原因的追蹤，其上次例外狀況具有「account\$1id 存取遭拒：1234567890」訊息**
```
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"
```
## 複雜關鍵字
使用複雜關鍵字以根據服務名稱、邊緣名稱或註釋值來尋找請求。若是服務和邊緣，您可以指定額外篩選條件表達式以套用到服務或邊緣。若是註釋，您可以使用布林值、數字或字串運算子，篩選含特定索引鍵的註釋值。
**複雜關鍵字**
+ `annotation[key]` – 具有欄位*索引鍵*的註釋值。註釋值可以是布林值、數字或字串，所以您可以使用任何這些類型的比較運算子。您可以將此關鍵字與 `service`或 `edge`關鍵字結合使用。包含點 （句點） 的註釋索引鍵必須以方括號 (**【 】**) 包裝。
+ `edge(source, destination) {filter}` – 服務*來源*和*目的地*之間的連線。選用的大括號可包含篩選表達式，以套用到此連線的服務。
+ `group.name / group.arn` – 群組篩選條件表達式的值，由群組名稱或群組 ARN 參考。
+ `json` – JSON 根本原因物件。如需以程式設計方式建立 JSON 實體的步驟，請參閱[從 AWS X-Ray 取得資料](xray-api-gettingdata.md)。
+ `service(name) {filter}` – 具有*名稱*的服務。選用的大括號可包含篩選表達式，以套用到服務所建立的區段。
使用 服務關鍵字來尋找針對追蹤映射上特定節點之請求的追蹤。
複雜關鍵字運算子會尋找已設定或未設定指定金鑰的區段。
**複雜關鍵字運算子**
+ none – 如果已設定關鍵字，則表達式為 true。如果關鍵字為布林值類型，則會評估為布林值。
+ `!` – 若未設定關鍵字，表示表達式為 true。如果關鍵字為布林值類型，則會評估為布林值。
+ `=`，`!=` – 比較關鍵字的值。
+ `edge(source, destination) {filter}` – 服務*來源*和*目的地*之間的連線。選用的大括號可包含篩選表達式，以套用到此連線的服務。
+ `annotation[key]` – 具有欄位*索引鍵*的註釋值。註釋值可以是布林值、數字或字串，所以您可以使用任何這些類型的比較運算子。您可以將此關鍵字與 `service`或 `edge`關鍵字結合使用。
+ `json` – JSON 根本原因物件。如需以程式設計方式建立 JSON 實體的步驟，請參閱[從 AWS X-Ray 取得資料](xray-api-gettingdata.md)。
使用 服務關鍵字來尋找針對追蹤映射上特定節點之請求的追蹤。
**Example – 服務篩選條件**
包含對 `api.example.com` 的呼叫且發生故障 (500 系列錯誤) 的請求。
```
service("api.example.com") { fault }
```
您可以排除服務名稱，以將篩選條件表達式套用到服務地圖中的所有節點。
**Example – 服務篩選條件**
造成追蹤映射上任何位置故障的請求。
```
service() { fault }
```
邊緣關鍵字可將篩選條件表達式套用到兩個節點之間的連線。
**Example – 邊緣篩選條件**
`api.example.com` 服務對 `backend.example.com` 發出呼叫但因錯誤而失敗的請求。
```
edge("api.example.com", "backend.example.com") { error }
```
您也可以搭配使用 `!` 運算子與服務和邊緣關鍵字，以排除其他篩選條件表達式結果的服務或邊緣。
**Example – 服務和請求篩選條件**
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")
```
**Example – 服務和回應時間篩選條件**
尋找`http url`設定 且回應時間大於 2 秒的追蹤。
```
http.url AND responseTime > 2
```
對於註釋，您可以呼叫`annotation[key]`設定 的所有追蹤，或使用對應於 值類型的比較運算子。
**Example – 註釋與字串值**
含名稱為 `gameid`、字串值為 `"817DL6VO"` 之註釋的請求。
```
annotation[gameid] = "817DL6VO"
```
**Example – 已設定註釋**
具有名為 `age` 集合的註釋的請求。
```
annotation[age]
```
**Example – 未設定註釋**
沒有已命名註釋`age`集的請求。
```
!annotation[age]
```
**Example – 註釋與數值**
含註釋存留期且數值大於 29 的請求。
```
annotation[age] > 29
```
**Example – 註釋結合服務或邊緣**
```
service { annotation[request.id] = "917DL6VO" }
```
```
edge { source.annotation[request.id] = "916DL6VO" }
```
```
edge { destination.annotation[request.id] = "918DL6VO" }
```
**Example – 具有使用者的 群組**
追蹤符合`high_response_time`群組篩選條件 （例如 `responseTime > 3`) 且使用者名為 Alice 的請求。
```
group.name = "high_response_time" AND user = "alice"
```
**Example – 具有根本原因實體的 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 服務。這兩個節點的名稱相同，但類型不同。標準的服務篩選條件可尋找這兩種追蹤。
**Example – 服務篩選條件**
包含任何名為 `random-name` 服務上的錯誤的請求。
```
service("random-name") { error }
```
使用 `id` 函數來縮小搜尋範圍至函數本身的錯誤，而不含服務的錯誤。
**Example – 具有 ID 函數的服務篩選條件**
包含名為 `random-name`、類型為 `AWS::Lambda::Function` 服務上的錯誤的請求。
```
service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
```
若要依據類型來搜尋節點，您也可以完全排除名稱。
**Example – 具有 ID 函數和服務類型的服務篩選條件**
包含類型為 `AWS::Lambda::Function` 服務上的錯誤的請求。
```
service(id(type: "AWS::Lambda::Function")) { error }
```
若要搜尋特定節點 AWS 帳戶，請指定帳戶 ID。
**Example – 具有 ID 函數和帳戶 ID 的服務篩選條件**
在特定帳戶 ID 內包含服務的請求`AWS::Lambda::Function`。
```
service(id(account.id: "account-id"))
```