本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 AWS X-Ray 追蹤 in AWS AppSync 中的請求
您可以使用 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) 追蹤在 AWS AppSync 中執行的請求。您可以在可使用 X-Ray 的所有 AWS 區域中使用 X-Ray with AWS AppSync。X-Ray 為您提供整個 GraphQL 請求的詳細概觀。這可讓您分析 API 及其基礎解析程式和資料來源中的延遲。您可以使用 X-Ray 服務映射來檢視請求的延遲，包括與 X-Ray 整合的任何 AWS 服務。您也可以設定取樣規則，根據您指定的條件，告訴 X-Ray 要記錄哪些請求，以及取樣率。
如需在 X-Ray 中取樣的詳細資訊，請參閱 [AWS X-Ray 主控台中的設定取樣規則](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)。
## 設定與組態
您可以透過 AWS AppSync 主控台啟用 GraphQL API 的 X-Ray 追蹤。
1. 登入 AWS AppSync 主控台。
1. 在導覽窗格中選擇 **Settings (設定)**。
1. 在 **X-Ray** 下，開啟 **Enable X-Ray (啟用 X-Ray)**。
1. 選擇**儲存**。現在已為您的 API 啟用 X-Ray 追蹤。
如果您使用的是 AWS CLI 或 AWS CloudFormation，您也可以在建立新的 AWS AppSync API 時啟用 X-Ray 追蹤，或將 `xrayEnabled` 屬性設定為 來更新 existing AWS AppSync API`true`。
為 an AWS AppSync API 啟用 X-Ray 追蹤時，會在您的帳戶中自動建立具有 AWS Identity and Access Management [適當許可的服務連結角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html)。這可讓 AWS AppSync 以安全的方式將追蹤傳送至 X-Ray。
## 使用 X-Ray 追蹤您的 API
### 抽樣
透過使用抽樣規則，您可以控制在 AWS AppSync 中記錄的資料量，並可即時修改抽樣行為，而無需修改或重新部署程式碼。例如，此規則使用 API ID `3n572shhcpfokwhdnq1ogu59v6` 對 GraphQL API 的請求進行取樣。
+ **規則名稱** — `test-sample`
+ **優先順序** — `10`
+ **儲槽大小** — `10`
+ **固定頻率** — `10`
+ **服務名稱** — `*`
+ **服務類型** — `AWS::AppSync::GraphQLAPI`
+ **HTTP 方法** — `*`
+ **資源 ARN** — `arn:aws:appsync:us-west-2:123456789012:apis/3n572shhcpfokwhdnq1ogu59v6`
+ **主機** — `*`
### 了解追蹤
當您為 GraphQL API 啟用 X-Ray 追蹤時，您可以使用 X-Ray 追蹤詳細資訊頁面來檢查對 API 提出請求的詳細延遲資訊。以下範例顯示此特定請求的追蹤檢視以及服務對應。請求是對名為 `postAPI`且具有 Post 類型的 API 提出，其資料包含在名為 的 Amazon DynamoDB 資料表中`PostTable-Example`。
下列追蹤影像對應下列 GraphQL 查詢：
```
query getPost {
getPost(id: "1") {
id
title
}
}
```
`getPost` 查詢的解析程式使用基礎 DynamoDB 資料來源。下列追蹤檢視顯示對 DynamoDB 的呼叫，以及查詢執行各個部分的延遲：
![\[Trace view showing client request, postAPI, and DynamoDB with durations and request details.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/xray-getpost-trace-view.png)
+ 在上述影像中，`/getPost` 表示要解析之元素的完整路徑。在這種情況下，因為 `getPost` 是根 `Query` 類型的欄位，它直接出現在路徑的根之後。
+ `requestMappingTemplateEvaluation` 代表 AWS AppSync 在查詢中評估此元素的請求映射範本所花費的時間。
+ `Query.getPost` 表示類型和欄位 (格式為 `Type.field`)。它可以包含多個子區段，取決於 API 的結構和要追蹤的請求而定。
+ `DynamoDB` 表示附加至此解析程式的資料來源。它包含對 DynamoDB 進行網路呼叫以解析 欄位的延遲。
+ `responseMappingTemplateEvaluation` 代表 AWS AppSync 在查詢中評估此元素的回應映射範本所花費的時間。
當您在 X-Ray 中檢視追蹤時，您可以選擇子區段並探索詳細檢視，以取得 AWS 有關 AppSync 區段中子區段的其他內容和中繼資料資訊。
對於某些深度巢狀或複雜的查詢，請注意交付至 X-Ray by AWS AppSync 的區段可以大於區段文件允許的大小上限，如[AWS X-Ray 區段文件](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html)所定義。X-Ray 不會顯示超過限制的區段。