本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS X-Ray 範例應用程式 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 AWS X-Ray [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray) 範例應用程式可在 GitHub 上取得，顯示使用 AWS X-Ray 開發套件來檢測傳入 HTTP 呼叫、DynamoDB SDK 用戶端和 HTTP 用戶端。範例應用程式使用 CloudFormation 來建立 DynamoDB 資料表、在執行個體上編譯 Java 程式碼，以及執行 X-Ray 協助程式，無需任何其他組態。 請參閱 [Scorekeep 教學](scorekeep-tutorial.md)課程，以使用 AWS 管理主控台 或 開始安裝和使用經檢測的範例應用程式 AWS CLI。 ![\[Scorekeep 使用 AWS X-Ray 開發套件來檢測傳入 HTTP 呼叫、DynamoDB SDK 用戶端和 HTTP 用戶端\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-flow.png) 範例包含前端 Web 應用程式、它呼叫的 API，以及它用來存放資料的 DynamoDB 資料表。具有[篩選條件](xray-sdk-java-filters.md)、[外掛程式](xray-sdk-java-configuration.md)和[檢測 AWS SDK 用戶端](xray-sdk-java-awssdkclients.md)的基本檢測會顯示在專案的`xray-gettingstarted`分支中。這次您在[入門教學](scorekeep-tutorial.md)中部署的項目。由於此分支僅包含基本項目，您可以將它針對 `master` 分支進行 diff，來快速了解基本項目。 ![\[Service map showing client interaction with Scorekeep container and related AWS 服務.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) 範例應用程式會在這些檔案中示範基本檢測： + **HTTP 請求篩選條件** – [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java) + **AWS SDK 用戶端檢測** – [https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle](https://github.com/awslabs/eb-java-scorekeep/tree/xray/build.gradle) 應用程式`xray`分支包括使用 [HTTPClient](xray-sdk-java-httpclients.md)、[標註](xray-sdk-java-segment.md)、[SQL 查詢](xray-sdk-java-sqlclients.md)、[自訂子區段](xray-sdk-java-subsegments.md)、經檢測的 [AWS Lambda](xray-services-lambda.md)函數，以及經[檢測的初始化程式碼和指令碼](scorekeep-startup.md)。 為了支援使用者登入並在瀏覽器 適用於 JavaScript 的 AWS SDK 中使用 ，`xray-cognito`分支會新增 Amazon Cognito 以支援使用者身分驗證和授權。透過從 Amazon Cognito 擷取的登入資料，Web 應用程式也會將追蹤資料傳送至 X-Ray，以從用戶端的觀點記錄請求資訊。瀏覽器用戶端會在追蹤地圖上顯示為自己的節點，並記錄其他資訊，包括使用者正在檢視的頁面 URL，以及使用者的 ID。 最後，`xray-worker`分支會新增經過檢測的 Python Lambda 函數，可獨立執行，處理來自 Amazon SQS 佇列的項目。Scorekeep 會在每次遊戲結束時新增項目到佇列中。CloudWatch Events 觸發的 Lambda 工作者每隔幾分鐘從佇列提取項目，並處理它們以將遊戲記錄存放在 Amazon S3 中進行分析。 **Topics** + [Scorekeep 範例應用程式入門](scorekeep-tutorial.md) + [手動檢測 AWS SDK 用戶端](scorekeep-sdkclients.md) + [建立其他子區段](scorekeep-subsegments.md) + [記錄標註、中繼資料及使用者 ID](scorekeep-annotations.md) + [檢測傳出的 HTTP 呼叫](scorekeep-httpclient.md) + [檢測 PostgreSQL 資料庫的呼叫](scorekeep-postgresql.md) + [檢測 AWS Lambda 函數](scorekeep-lambda.md) + [檢測啟動程式碼](scorekeep-startup.md) + [檢測指令碼](scorekeep-scripts.md) + [檢測 Web 應用程式用戶端](scorekeep-client.md) + [在工作者執行緒中使用受檢測用戶端](scorekeep-workerthreads.md) # Scorekeep 範例應用程式入門 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 本教學課程使用 [Scorekeep 範例應用程式的](xray-scorekeep.md)分支，該`xray-gettingstarted`分支使用 CloudFormation 來建立和設定在 Amazon ECS 上執行範例應用程式和 X-Ray 協助程式的資源。應用程式使用 Spring 架構實作 JSON Web API 和 適用於 Java 的 AWS SDK ，將資料保留至 Amazon DynamoDB。應用程式中的 servlet 篩選條件會檢測應用程式提供的所有傳入請求，而 AWS SDK 用戶端上的請求處理常式會檢測對 DynamoDB 的下游呼叫。 您可以使用 AWS 管理主控台 或 遵循本教學課程 AWS CLI。 **Topics** + [先決條件](#xray-gettingstarted-prereqs) + [使用 CloudFormation 安裝 Scorekeep 應用程式](#xray-gettingstarted-deploy) + [產生追蹤資料](#xray-gettingstarted-generate-traces) + [在 中檢視追蹤映射 AWS 管理主控台](#xray-gettingstarted-console) + [設定 Amazon SNS 通知](#xray-gettingstarted-notifications) + [探索範例應用程式](#xray-gettingstarted-sample) + [選用：最低權限政策](#xray-gettingstarted-security) + [清除](#xray-gettingstarted-cleanup) + [後續步驟](#xray-gettingstarted-nextsteps) ## 先決條件 本教學課程使用 CloudFormation 來建立和設定執行範例應用程式和 X-Ray 協助程式的資源。安裝和執行教學課程需要下列先決條件： 1. 如果您使用具有有限許可的 IAM 使用者，請在 [IAM 主控台](https://console.aws.amazon.com/iam)中新增下列使用者政策： + `AWSCloudFormationFullAccess` – 存取和使用 CloudFormation + `AmazonS3FullAccess` – 使用 將範本檔案上傳至 CloudFormation AWS 管理主控台 + `IAMFullAccess` – 建立 Amazon ECS 和 Amazon EC2 執行個體角色 + `AmazonEC2FullAccess` – 建立 Amazon EC2 資源 + `AmazonDynamoDBFullAccess` – 建立 DynamoDB 資料表 + `AmazonECS_FullAccess` – 建立 Amazon ECS 資源 + `AmazonSNSFullAccess` – 建立 Amazon SNS 主題 + `AWSXrayReadOnlyAccess` – 用於在 X-Ray 主控台中檢視追蹤映射和追蹤的許可 1. 若要使用 執行教學課程 AWS CLI，[請安裝 CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 2.7.9 版或更新版本，並使用上一個步驟中的使用者[設定 CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config)。 AWS CLI 使用 使用者設定 時，請確定已設定 區域。如果未設定區域，您將需要附加`--region AWS-REGION`到每個 CLI 命令。 1. 確保已安裝 [Git](https://github.com/git-guides/install-git)，以複製範例應用程式儲存庫。 1. 使用以下程式碼範例來複製 Scorekeep 儲存庫的`xray-gettingstarted`分支： ``` git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted ``` ## 使用 CloudFormation 安裝 Scorekeep 應用程式 ------ #### [ AWS 管理主控台 ] **使用 安裝範例應用程式 AWS 管理主控台** 1. 開啟 [ CloudFormation 主控台](https://console.aws.amazon.com/cloudformation/) 1. 選擇**建立堆疊**，然後從下拉式功能表中選擇**使用新資源**。 1. 在 **Specify template (指定範本)** 區段中，選擇 **Upload a template file (上傳範本檔案)**。 1. 選取**選擇檔案**，導覽至複製 git 儲存庫時建立的`xray-scorekeep/cloudformation`資料夾，然後選擇`cf-resources.yaml`檔案。 1. 選擇 **Next** (下一步) 繼續。 1. 在**堆疊名稱**文字方塊`scorekeep`中輸入 ，然後選擇頁面底部的**下一步**以繼續。請注意，本教學課程的其餘部分假設堆疊名為 `scorekeep`。 1. 捲動至**設定堆疊選項**頁面底部，然後選擇**下一步**以繼續。 1. 捲動至**檢閱**頁面底部，選擇確認 CloudFormation 可以使用自訂名稱建立 IAM 資源的核取方塊，然後選擇**建立堆疊**。 1. 現在正在建立 CloudFormation 堆疊。堆疊狀態會`CREATE_IN_PROGRESS`維持大約五分鐘，然後再變更為 `CREATE_COMPLETE`。狀態會定期重新整理，或者您可以重新整理頁面。 ------ #### [ AWS CLI ] **使用 安裝範例應用程式 AWS CLI** 1. 導覽至您先前在教學課程中複製的`xray-scorekeep`儲存庫`cloudformation`資料夾： ``` cd xray-scorekeep/cloudformation/ ``` 1. 輸入下列 AWS CLI 命令來建立 CloudFormation 堆疊： ``` aws cloudformation create-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. 等到 CloudFormation 堆疊狀態為 `CREATE_COMPLETE`，這大約需要五分鐘。使用下列 AWS CLI 命令來檢查狀態： ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## 產生追蹤資料 範例應用程式包含前端 Web 應用程式。使用 Web 應用程式產生 API 的流量，並將追蹤資料傳送至 X-Ray。首先，使用 AWS 管理主控台 或 擷取 Web 應用程式 URL AWS CLI： ------ #### [ AWS 管理主控台 ] **使用 尋找應用程式 URL AWS 管理主控台** 1. 開啟 [ CloudFormation 主控台](https://console.aws.amazon.com/cloudformation/) 1. 從清單中選擇`scorekeep`堆疊。 1. 選擇`scorekeep`堆疊頁面上**的輸出**索引標籤，然後選擇 `LoadBalancerUrl` URL 連結以開啟 Web 應用程式。 ------ #### [ AWS CLI ] **使用 尋找應用程式 URL AWS CLI** 1. 使用下列命令來顯示 Web 應用程式的 URL： ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].Outputs[0].OutputValue" ``` 1. 複製此 URL 並在瀏覽器中開啟 ，以顯示 Scorekeep Web 應用程式。 ------ **使用 Web 應用程式產生追蹤資料** 1. 選擇 **Create (建立)** 來產生使用者及工作階段。 1. 輸入 **game name (遊戲名稱)**、將 **Rules (規則)** 設為 **Tic Tac Toe (井字遊戲)**，然後選擇 **Create (建立)**。 1. 選擇 **Play (遊玩)** 來啟動遊戲。 1. 選擇一個磚來進行移動並變更遊戲狀態。 每個步驟都會產生對 API 的 HTTP 請求，以及對 DynamoDB 的下游呼叫，以讀取和寫入使用者、工作階段、遊戲、移動和狀態資料。 ## 在 中檢視追蹤映射 AWS 管理主控台 您可以在 X-Ray 和 CloudWatch 主控台中查看範例應用程式產生的追蹤映射和追蹤。 ------ #### [ X-Ray console ] **使用 X-Ray 主控台** 1. 開啟 [X-Ray 主控台](https://console.aws.amazon.com/xray/home#/service-map)的追蹤映射頁面。 1. 主控台會顯示 X-Ray 從應用程式傳送的追蹤資料產生的服務圖表。請務必視需要調整追蹤映射的期間，以確保它在您第一次啟動 Web 應用程式後會顯示所有追蹤。 ![\[X-Ray 追蹤映射期間\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/xray-console-time-period-15-minutes.png) 追蹤映射會顯示 Web 應用程式用戶端、在 Amazon ECS 中執行的 API，以及應用程式使用的每個 DynamoDB 資料表。每個向應用程式發出的請求都會在命中 API 時受到追蹤、產生向下游服務發出的請求並完成，其數量上限為可設定的每秒請求數量上限。 您可以在服務圖表中選擇任何節點來檢視產生流量至該節點的請求追蹤。目前，Amazon SNS 節點為黃色。向下切入來了解原因。 ![\[X-Ray 主控台追蹤映射頁面\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-ECS.png) **尋找錯誤原因** 1. 選擇名為 **SNS** 的節點。節點詳細資訊面板隨即顯示。 1. 選擇 **View traces (檢視追蹤)** 以存取 **Trace overview (追蹤概觀)** 畫面。 1. 從 **Trace list (追蹤清單)** 中選擇追蹤。此追蹤不具有方法或 URL，因為它是在啟動期間，而非回應傳入請求時記錄。 ![\[從 Trace list (追蹤清單) 選擇追蹤\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-tracelist-sns.png) 1. 選擇頁面底部的 Amazon SNS 區段中的錯誤狀態圖示，以開啟 SNS 子區段的**例外**狀況頁面。 ![\[選擇錯誤狀態圖示以開啟 Amazon SNS 子區段的例外狀況頁面\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-timeline-sns-ecs.png) 1. X-Ray SDK 會自動擷取經 AWS 檢測的 SDK 用戶端擲回的例外狀況，並記錄堆疊追蹤。 ![\[顯示擷取到的異常及記錄堆疊追蹤的 Exceptions (異常) 標籤\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-exception.png) ------ #### [ CloudWatch console ] **使用 CloudWatch 主控台** 1. 開啟 CloudWatch 主控台的 [X-Ray 追蹤映射](https://console.aws.amazon.com/cloudwatch/home#xray:service-map/map)頁面。 1. 主控台會顯示 X-Ray 從應用程式傳送的追蹤資料產生的服務圖表。請務必視需要調整追蹤映射的期間，以確保它在您第一次啟動 Web 應用程式後會顯示所有追蹤。 ![\[CloudWatch 追蹤映射期間\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/cw-console-service-map-time-period-15-minutes.png) 追蹤映射會顯示 Web 應用程式用戶端、在 Amazon EC2 中執行的 API，以及應用程式使用的每個 DynamoDB 資料表。每個向應用程式發出的請求都會在命中 API 時受到追蹤、產生向下游服務發出的請求並完成，其數量上限為可設定的每秒請求數量上限。 您可以在服務圖表中選擇任何節點來檢視產生流量至該節點的請求追蹤。目前，Amazon SNS 節點為橘色。向下切入來了解原因。 ![\[X-Ray 主控台追蹤映射頁面\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-before-ECS.png) **尋找錯誤原因** 1. 選擇名為 **SNS** 的節點。SNS 節點詳細資訊面板會顯示在地圖下方。 1. 選擇**檢視追蹤**以存取**追蹤**頁面。 1. 新增頁面底部，從追蹤清單中選擇**追蹤**。此追蹤不具有方法或 URL，因為它是在啟動期間，而非回應傳入請求時記錄。 ![\[從 Trace list (追蹤清單) 選擇追蹤\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-cw-tracelist-sns-ecs.png) 1. 選擇區段時間軸底部的 Amazon SNS 子區段，然後選擇 SNS 子區段的**例外狀況**索引標籤，以檢視例外狀況詳細資訊。 ![\[檢視 Amazon SNS 子區段的例外狀況索引標籤\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-cw-timeline-sns-ecs.png) ------ 原因指出在 `WebConfig` 類別中對 `createSubscription` 發出的呼叫內所提供的電子郵件地址無效。在下一節中，我們將修正此問題。 ## 設定 Amazon SNS 通知 Scorekeep 使用 Amazon SNS 在使用者完成遊戲時傳送通知。當應用程式啟動時，它會嘗試為 CloudFormation 堆疊參數中定義的電子郵件地址建立訂閱。該呼叫目前失敗。設定通知電子郵件以啟用通知，並解決追蹤映射中反白顯示的失敗。 ------ #### [ AWS 管理主控台 ] **使用 設定 Amazon SNS 通知 AWS 管理主控台** 1. 開啟 [ CloudFormation 主控台](https://console.aws.amazon.com/cloudformation/) 1. 選擇清單中`scorekeep`堆疊名稱旁的選項按鈕，然後選擇**更新**。 1. 確定已選擇**使用目前的範本**，然後在**更新堆疊**頁面上按一下**下一步**。 1. 在清單中尋找**電子郵件**參數，並以有效的電子郵件地址取代預設值。 ![\[更新電子郵件組態\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-cf-email-update.png) 1. 向下捲動到頁面底部並選擇 **Next** (下一步)。 1. 捲動至**檢閱**頁面底部，選擇確認 CloudFormation 可以使用自訂名稱建立 IAM 資源的核取方塊，然後選擇**更新堆疊**。 1. CloudFormation 堆疊現在正在更新。堆疊狀態會`UPDATE_IN_PROGRESS`維持大約五分鐘，然後再變更為 `UPDATE_COMPLETE`。狀態會定期重新整理，或者您可以重新整理頁面。 ------ #### [ AWS CLI ] **使用 設定 Amazon SNS 通知 AWS CLI** 1. 導覽至您先前建立的`xray-scorekeep/cloudformation/`資料夾，然後在文字編輯器中開啟 `cf-resources.yaml` 檔案。 1. 在**電子郵件**參數中尋找`Default`值，並將其從 *UPDATE\$1ME* 變更為有效的電子郵件地址。 ``` Parameters: Email: Type: String Default: UPDATE_ME # <- change to a valid abc@def.xyz email address ``` 1. 從 `cloudformation` 資料夾，使用下列 AWS CLI 命令更新 CloudFormation 堆疊： ``` aws cloudformation update-stack --stack-name scorekeep --capabilities "CAPABILITY_NAMED_IAM" --template-body file://cf-resources.yaml ``` 1. 等到 CloudFormation 堆疊狀態為 `UPDATE_COMPLETE`，這將需要幾分鐘的時間。使用下列 AWS CLI 命令來檢查狀態： ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ 更新完成時，Scorekeep 會重新啟動並建立 SNS 主題訂閱。檢查您的電子郵件以確認訂閱，在您完成遊戲時查看更新。開啟追蹤映射，以確認對 SNS 的呼叫不再失敗。 ## 探索範例應用程式 範例應用程式是 Java 中的 HTTP Web API，設定為使用適用於 Java 的 X-Ray 開發套件。當您使用 CloudFormation 範本部署應用程式時，它會建立在 ECS 上執行 Scorekeep 所需的 DynamoDB 資料表、Amazon ECS 叢集和其他服務。ECS 的任務定義檔案是透過 CloudFormation 建立。此檔案定義 ECS 叢集中每個任務使用的容器映像。這些影像是從官方 X-Ray 公有 ECR 取得。scorekeep API 容器映像使用 Gradle 編譯 API。Scorekeep 前端容器的容器映像會使用 nginx 代理伺服器為前端提供服務。此伺服器會將請求路由至以 /api 開頭的路徑至 API。 為了檢測傳入 HTTP 請求，應用程式會新增軟體開發套件提供的 `TracingFilter`。 **Example src/main/java/scorekeep/WebConfig.java - servlet 篩選條件** ``` import javax.servlet.Filter; import [com.amazonaws.xray.javax.servlet.AWSXRayServletFilter](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/javax/servlet/AWSXRayServletFilter.html); ... @Configuration public class WebConfig { @Bean public Filter TracingFilter() { return new AWSXRayServletFilter("Scorekeep"); } ... ``` 此篩選條件會傳送應用程式處理的所有傳入請求相關追蹤資料，包括請求 URL、方法、回應狀態、開始時間及結束時間。 應用程式也會使用 對 DynamoDB 進行下游呼叫 適用於 Java 的 AWS SDK。為了檢測這些呼叫，應用程式只會將 AWS SDK 相關的子模組做為相依性，而適用於 Java 的 X-Ray 開發套件會自動檢測所有 AWS SDK 用戶端。 應用程式使用 `Docker`建置執行個體上的原始程式碼，並使用 `Gradle Docker Image`和 `Scorekeep API Dockerfile` 檔案來執行 Gradle 在其 產生的可執行 JAR`ENTRYPOINT`。 **Example 使用 Docker 透過 Gradle Docker Image 建置** ``` docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build ``` **Example Dockerfile ENTRYPOINT** ``` ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ] ``` `build.gradle` 檔案會在編譯期間，透過將其宣告為依存項目，來從 Maven 下載軟體開發套件子模組。 **Example build.gradle -- 相依性** ``` ... dependencies { compile("org.springframework.boot:spring-boot-starter-web") testCompile('org.springframework.boot:spring-boot-starter-test') compile('com.amazonaws:aws-java-sdk-dynamodb') compile("com.amazonaws:aws-xray-recorder-sdk-core") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk") compile("com.amazonaws:aws-xray-recorder-sdk-aws-sdk-instrumentor") ... } dependencyManagement { imports { mavenBom("com.amazonaws:aws-java-sdk-bom:1.11.67") mavenBom("com.amazonaws:aws-xray-recorder-sdk-bom:2.11.0") } } ``` 核心、 AWS SDK 和 AWS SDK Instrumentor 子模組都是自動檢測使用 AWS SDK 進行的任何下游呼叫所需的。 若要將原始區段資料轉送至 X-Ray API，X-Ray 協助程式需要接聽 UDP 連接埠 2000 上的流量。若要這樣做，應用程式會在與 ECS 上的 Scorekeep 應用程式一起部署的容器中執行 X-Ray 協助程式，做為*附屬容器*。如需詳細資訊，請參閱 [X-Ray 協助程式](xray-daemon.md)主題。 **Example ECS 任務定義中的 X-Ray 協助程式容器定義** ``` ... Resources: ScorekeepTaskDefinition: Type: AWS::ECS::TaskDefinition Properties: ContainerDefinitions: ... - Cpu: '256' Essential: true Image: amazon/aws-xray-daemon MemoryReservation: '128' Name: xray-daemon PortMappings: - ContainerPort: '2000' HostPort: '2000' Protocol: udp ... ``` 適用於 Java 的 X-Ray 開發套件提供名為 的類別`AWSXRay`，提供全域記錄器，您可以用來檢測程式碼`TracingHandler`的 。您可以設定全域記錄器來自訂為傳入 HTTP 呼叫建立區段的 `AWSXRayServletFilter`。範例包括 `WebConfig` 類別中的靜態區塊，該區塊會使用外掛程式和抽樣規則設定全域記錄器。 **Example src/main/java/scorekeep/WebConfig.java - 記錄器** ``` import com.amazonaws.xray.AWSXRay; import com.amazonaws.xray.AWSXRayRecorderBuilder; import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter; import com.amazonaws.xray.plugins.ECSPlugin; import com.amazonaws.xray.plugins.EC2Plugin; import com.amazonaws.xray.strategy.sampling.LocalizedSamplingStrategy; ... @Configuration public class WebConfig { ... static { AWSXRayRecorderBuilder builder = AWSXRayRecorderBuilder.standard().withPlugin(new ECSPlugin()).withPlugin(new EC2Plugin()); URL ruleFile = WebConfig.class.getResource("/sampling-rules.json"); builder.withSamplingStrategy(new LocalizedSamplingStrategy(ruleFile)); AWSXRay.setGlobalRecorder(builder.build()); ... } } ``` 此範例使用建立器從名為 `sampling-rules.json` 的檔案載入抽樣規則。抽樣規則會判斷軟體開發套件記錄傳入請求區段的速率。 **Example src/main/java/resources/sampling-rules.json** ``` { "version": 1, "rules": [ { "description": "Resource creation.", "service_name": "*", "http_method": "POST", "url_path": "/api/*", "fixed_target": 1, "rate": 1.0 }, { "description": "Session polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/session/*", "fixed_target": 0, "rate": 0.05 }, { "description": "Game polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/game/*/*", "fixed_target": 0, "rate": 0.05 }, { "description": "State polling.", "service_name": "*", "http_method": "GET", "url_path": "/api/state/*/*/*", "fixed_target": 0, "rate": 0.05 } ], "default": { "fixed_target": 1, "rate": 0.1 } } ``` 抽樣規則檔案會定義四個自訂抽樣規則及預設規則。針對每個傳入請求，軟體開發套件會依照定義規則的順序評估自訂規則。軟體開發套件會套用第一個與請求方法、路徑及服務名稱相符的規則。針對 Scorekeep，第一個規則會透過以 1.0 的速率每秒套用一個請求的單一固定目標，或是在滿足固定目標之後套用 100% 的請求，來追補所有 POST 請求 (資源建立呼叫)。 其他三個自訂規則會在沒有指向工作階段、遊戲和狀態讀取 (GET 請求) 固定目標的情況下套用 5% 的速率 這會將前端為了確保內容處於最新狀態，每幾秒鐘自動發出定期呼叫的追蹤數量降至最低。針對所有其他請求，檔案會定義每秒單一請求的預設速率及 10% 的速率。 範例應用程式也會示範如何使用進階功能 (例如手動軟體開發套件用戶端檢測、建立額外子區段及傳出 HTTP 呼叫)。如需詳細資訊，請參閱[AWS X-Ray 範例應用程式](xray-scorekeep.md)。 ## 選用：最低權限政策 Scorekeep ECS 容器使用完整存取政策存取資源，例如 `AmazonSNSFullAccess`和 `AmazonDynamoDBFullAccess`。使用完整存取政策不是生產應用程式的最佳實務。下列範例會更新 DynamoDB IAM 政策，以改善應用程式的安全性。若要進一步了解 IAM 政策中的安全最佳實務，請參閱 [AWS X-Ray 的身分和存取管理](security-iam.md)。 **Example cf-resources.yaml 範本 ECSTaskRole 定義** ``` ECSTaskRole: Type: AWS::IAM::Role Properties: AssumeRolePolicyDocument: Version: "2012-10-17" Statement: - Effect: "Allow" Principal: Service: - "ecs-tasks.amazonaws.com" Action: - "sts:AssumeRole" ManagedPolicyArns: - "arn:aws:iam::aws:policy/AmazonDynamoDBFullAccess" - "arn:aws:iam::aws:policy/AmazonSNSFullAccess" - "arn:aws:iam::aws:policy/AWSXrayFullAccess" RoleName: "scorekeepRole" ``` 若要更新政策，請先識別 DynamoDB 資源的 ARN。然後，您可以在自訂 IAM 政策中使用 ARN。最後，您將該政策套用到您的執行個體描述檔。 **若要識別 DynamoDB 資源的 ARN：** 1. 開啟 [DynamoDB 主控台](https://console.aws.amazon.com/dynamodbv2)。 1. 從左側導覽列中選擇**資料表**。 1. 選擇任一 `scorekeep-*`以顯示資料表詳細資訊頁面。 1. 在**概觀**索引標籤下，選擇**其他資訊**以展開區段，並檢視 Amazon Resource Name (ARN)。複製這個值。 1. 將 ARN 插入下列 IAM 政策，將 `AWS_REGION`和 `AWS_ACCOUNT_ID`值取代為您的特定區域和帳戶 ID。此新政策僅允許指定的動作，而非允許任何動作`AmazonDynamoDBFullAccess`的政策。 **Example** ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "ScorekeepDynamoDB", "Effect": "Allow", "Action": [ "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:DeleteItem", "dynamodb:GetItem", "dynamodb:Scan", "dynamodb:Query" ], "Resource": "arn:aws:dynamodb:us-east-1:111122223333:table/scorekeep-*" } ] } ``` ------ 應用程式建立的資料表遵循一致的命名慣例。您可以使用 `scorekeep-*` 格式來指示所有 Scorekeep 資料表。 **變更您的 IAM 政策** 1. 從 IAM 主控台開啟 [Scorekeep 任務角色 (scorekeepRole)](https://console.aws.amazon.com/iamv2/home#/roles/details/scorekeepRole)。 1. 選擇`AmazonDynamoDBFullAccess`政策旁的核取方塊，然後選擇**移除**以移除此政策。 1. 選擇**新增許可**，然後選擇**連接政策**，最後再選擇**建立政策**。 1. 選擇 **JSON** 索引標籤並貼到上面建立的政策中。 1. 選擇頁面底部的**下一步：標籤**。 1. 選擇頁面底部的**下一步：檢閱**。 1. 針對**名稱**，指派政策的名稱。 1. 選擇頁面底部的**建立政策**。 1. 將新建立的政策連接至`scorekeepRole`角色。連接的政策可能需要幾分鐘的時間才會生效。 如果您已將新政策連接至`scorekeepRole`角色，則必須先將其分離，才能刪除 CloudFormation 堆疊，因為此連接政策會封鎖堆疊遭到刪除。政策可以透過刪除政策來自動分離。 **移除您的自訂 IAM 政策** 1. 開啟 [IAM 主控台](https://console.aws.amazon.com/iam)。 1. 從左側導覽列中選擇**政策**。 1. 搜尋您在本節稍早建立的自訂政策名稱，然後選擇政策名稱旁的選項按鈕以反白顯示。 1. 選擇**動作**下拉式清單，然後選擇**刪除**。 1. 輸入自訂政策的名稱，然後選擇**刪除**以確認刪除。這會自動分離政策與`scorekeepRole`角色。 ## 清除 請依照下列步驟刪除 Scorekeep 應用程式資源： **注意** 如果您使用本教學課程的上一節建立並連接自訂政策，您必須先從 移除政策，`scorekeepRole`才能刪除 CloudFormation 堆疊。 ------ #### [ AWS 管理主控台 ] **使用 刪除範例應用程式 AWS 管理主控台** 1. 開啟 [ CloudFormation 主控台](https://console.aws.amazon.com/cloudformation/) 1. 選擇清單中`scorekeep`堆疊名稱旁的選項按鈕，然後選擇**刪除**。 1. CloudFormation 堆疊現在正在刪除。堆疊狀態將會`DELETE_IN_PROGRESS`持續幾分鐘，直到刪除所有資源為止。狀態會定期重新整理，或者您可以重新整理頁面。 ------ #### [ AWS CLI ] **使用 刪除範例應用程式 AWS CLI** 1. 輸入下列 AWS CLI 命令來刪除 CloudFormation 堆疊： ``` aws cloudformation delete-stack --stack-name scorekeep ``` 1. 等到 CloudFormation 堆疊不再存在，這大約需要五分鐘的時間。使用下列 AWS CLI 命令來檢查狀態： ``` aws cloudformation describe-stacks --stack-name scorekeep --query "Stacks[0].StackStatus" ``` ------ ## 後續步驟 在下一章 中進一步了解 X-Ray[AWS X-Ray 概念](xray-concepts.md)。 若要檢測您自己的應用程式，請進一步了解適用於 Java 的 X-Ray 開發套件或其他其中一個 X-Ray SDKs： + **適用於 Java 的 X-Ray 開發套件** – [AWS X-Ray 適用於 Java 的 SDK](xray-sdk-java.md) + **適用於 Node.js 的 X-Ray 開發套件** – [AWS 適用於 Node.js 的 X-Ray 開發套件](xray-sdk-nodejs.md) + **適用於 .NET 的 X-Ray 開發套件** – [AWS X-Ray 適用於 .NET 的 SDK](xray-sdk-dotnet.md) 若要在本機或 上執行 X-Ray 協助程式 AWS，請參閱 [AWS X-Ray 協助程式](xray-daemon.md)。 若要在 GitHub 上參與範例應用程式，請參閱 [eb-java-scorekeep](https://github.com/awslabs/eb-java-scorekeep/tree/xray-gettingstarted)。 # 手動檢測 AWS SDK 用戶端 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 當您在建置相依性中包含 AWS SDK Instrumentor 子模組時，適用於 Java 的 X-Ray 開發套件會自動檢測所有 SDK 用戶端。 [AWS](xray-sdk-java.md#xray-sdk-java-dependencies) 若要停用自動用戶端檢測，您可以移除 Instrumentor 子模組。這可讓您手動檢測一些特定用戶端而忽略其他用戶端，或使用不同用戶端上的不同追蹤處理常式。 為了說明檢測特定 AWS SDK 用戶端的支援，應用程式會將追蹤處理常式傳遞至 ，`AmazonDynamoDBClientBuilder`做為使用者、遊戲和工作階段模型中的請求處理常式。此程式碼變更會告知 SDK 使用這些用戶端來檢測對 DynamoDB 的所有呼叫。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/SessionModel.java) – 手動 AWS SDK 用戶端檢測** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.handlers.TracingHandler](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/handlers/TracingHandler.html); public class SessionModel { private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard() .withRegion(Constants.REGION) .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder())) .build(); private DynamoDBMapper mapper = new DynamoDBMapper(client); ``` 如果您從專案相依性中移除 AWS SDK Instrumentor 子模組，則只有手動檢測的 AWS SDK 用戶端會出現在追蹤映射中。 # 建立其他子區段 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 在使用者模型類別中，應用程式會手動建立子區段以分組 `saveUser` 函數內發出的所有下游呼叫，並新增中繼資料。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserModel.java) - 自訂子區段** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveUser(User user) { // Wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## UserModel.saveUser"); try { mapper.save(user); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` # 記錄標註、中繼資料及使用者 ID **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 在遊戲模型類別中，每次在 DynamoDB 中儲存遊戲時，應用程式都會記錄[中繼資料](xray-sdk-java-segment.md#xray-sdk-java-segment-metadata)區塊中的`Game`物件。應用程式還會另外在[標註](xray-sdk-java-segment.md#xray-sdk-java-segment-annotations)中記錄遊戲 ID，用於[篩選條件表達式](xray-console-filters.md)。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/GameModel.java) – 註釋和中繼資料** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... public void saveGame(Game game) throws SessionNotFoundException { // wrap in subsegment Subsegment subsegment = AWSXRay.beginSubsegment("## GameModel.saveGame"); try { // check session String sessionId = game.getSession(); if (sessionModel.loadSession(sessionId) == null ) { throw new SessionNotFoundException(sessionId); } Segment segment = AWSXRay.getCurrentSegment(); subsegment.putMetadata("resources", "game", game); segment.putAnnotation("gameid", game.getId()); mapper.save(game); } catch (Exception e) { subsegment.addException(e); throw e; } finally { AWSXRay.endSubsegment(); } } ``` 在移動控制器中，應用程式會使用 記錄[使用者 IDs](xray-sdk-java-segment.md#xray-sdk-java-segment-userid)`setUser`。區段會將使用者 ID 記錄在單獨的欄位中，並建立索引以用於搜尋。 **Example [src/main/java/scorekeep/MoveController.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveController.java) – 使用者 ID** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); ... @RequestMapping(value="/{userId}", method=RequestMethod.POST) public Move newMove(@PathVariable String sessionId, @PathVariable String gameId, @PathVariable String userId, @RequestBody String move) throws SessionNotFoundException, GameNotFoundException, StateNotFoundException, RulesException { AWSXRay.getCurrentSegment().setUser(userId); return moveFactory.newMove(sessionId, gameId, userId, move); } ``` # 檢測傳出的 HTTP 呼叫 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 使用者工廠類別顯示應用程式如何使用適用於 Java 的 X-Ray 開發套件版本 `HTTPClientBuilder` 來檢測傳出的 HTTP 呼叫。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/UserFactory.java) – HTTPClient 檢測** ``` import [com.amazonaws.xray.proxies.apache.http.HttpClientBuilder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/proxies/apache/http/HttpClientBuilder.html); public String randomName() throws IOException { CloseableHttpClient httpclient = HttpClientBuilder.create().build(); HttpGet httpGet = new HttpGet("http://uinames.com/api/"); CloseableHttpResponse response = httpclient.execute(httpGet); try { HttpEntity entity = response.getEntity(); InputStream inputStream = entity.getContent(); ObjectMapper mapper = new ObjectMapper(); Map jsonMap = mapper.readValue(inputStream, Map.class); String name = jsonMap.get("name"); EntityUtils.consume(entity); return name; } finally { response.close(); } } ``` 若您目前使用 `org.apache.http.impl.client.HttpClientBuilder`，您可以直接使用一個用於 `com.amazonaws.xray.proxies.apache.http.HttpClientBuilder` 的項目將該類別的匯入陳述式切換出去。 # 檢測 PostgreSQL 資料庫的呼叫 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 `application-pgsql.properties` 檔案會將 X-Ray PostgreSQL 追蹤攔截器新增至 中建立的資料來源[https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java)。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/resources/application-pgsql.properties) – PostgreSQL 資料庫檢測** ``` spring.datasource.continue-on-error=true spring.jpa.show-sql=false spring.jpa.hibernate.ddl-auto=create-drop spring.datasource.jdbc-interceptors=com.amazonaws.xray.sql.postgres.TracingInterceptor spring.jpa.database-platform=org.hibernate.dialect.PostgreSQL94Dialect ``` **注意** 如需如何將 PostgreSQL 資料庫新增至應用程式環境的詳細資訊，請參閱[《 開發人員指南》中的使用 Elastic Beanstalk 設定](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.managing.db.html)資料庫。 *AWS Elastic Beanstalk * `xray` 分支中的 X-Ray 示範頁面包含示範，該示範使用經檢測的資料來源來產生追蹤，以顯示其產生的 SQL 查詢的相關資訊。導覽至執行中應用程式的 `/#/xray` 路徑，或選擇導覽列中的 **Powered by AWS X-Ray(採用 &xraylong; 技術)**，以查看示範頁面。 ![\[AWS X-Ray integration demo page showing game session tracing and SQL query tracing options.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-demo.png) 選擇 **Trace SQL queries (追蹤 SQL 查詢)** 以模擬遊戲工作階段，並將結果存放在連接的資料庫中。然後，選擇在 ** AWS X-Ray 中檢視追蹤**，以查看命中 API `/api/history`路由的追蹤篩選清單。 從清單中選擇其中一個追蹤以查看時間軸，包括 SQL 查詢。 ![\[Timeline view of a trace showing method, response, duration, and age for a GET request.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-trace-sql.png) # 檢測 AWS Lambda 函數 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 Scorekeep 使用兩個 AWS Lambda 函數。第一個是來自 `lambda` 分支的 Node.js 函數，會為新使用者產生隨機名稱。當使用者在未輸入名稱的情況下建立工作階段時，應用程式會使用 適用於 Java 的 AWS SDK呼叫名為 `random-name` 的函數。適用於 Java 的 X-Ray 開發套件會在子區段中記錄 Lambda 呼叫的相關資訊，就像使用經檢測的 AWS 開發套件用戶端進行的任何其他呼叫一樣。 **注意** 執行 `random-name` Lambda 函數需要在 Elastic Beanstalk 環境外部建立其他資源。如需詳細資訊和指示，請參閱讀我檔案：[AWS Lambda 整合](https://github.com/awslabs/eb-java-scorekeep/tree/xray/README.md#aws-lambda-integration)。 第二個函數 (`scorekeep-worker`) 是一種 Python 函數，會在 Scorekeep API 之外獨立執行。遊戲結束時，API 會將工作階段 ID 及遊戲 ID 寫入 SQS 佇列。工作者函數會從佇列讀取項目，並呼叫 Scorekeep API 來建構每個遊戲工作階段的完整記錄，以便在 Amazon S3 中儲存。 Scorekeep 包含建立這兩個函數的 CloudFormation 範本和指令碼。由於您需要將 X-Ray 開發套件與函數程式碼綁定，因此範本會建立不含任何程式碼的函數。部署 Scorekeep 時，包含在 `.ebextensions` 資料夾中的組態檔會建立包含軟體開發套件的來源套件，並使用 AWS Command Line Interface更新函數程式碼及組態。 **Topics** + [隨機名稱](#scorekeep-lambda-randomname) + [工作程序](#scorekeep-lambda-worker) ## 隨機名稱 Scorekeep 會在使用者未登入或未指定任何使用者名稱啟動遊戲工作階段時呼叫隨機名稱函數。當 Lambda 處理對 的呼叫時`random-name`，它會讀取[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)，其中包含由適用於 Java 的 X-Ray 開發套件所撰寫的追蹤 ID 和取樣決策。 對於每個取樣請求，Lambda 會執行 X-Ray 協助程式並寫入兩個區段。第一個區段會記錄叫用函數的 Lambda 呼叫相關資訊。此區段包含與 Scorekeep 記錄的子區段相同的資訊，但從 Lambda 觀點來看。第二個區段則代表函數進行的工作。 Lambda 透過函數內容將函數區段傳遞至 X-Ray SDK。當您檢測 Lambda 函數時，不會使用 SDK 為[傳入請求建立區段](xray-sdk-nodejs-middleware.md)。Lambda 提供區段，您可以使用 SDK 來檢測用戶端和寫入子區段。 ![\[顯示 scorekeep 如何呼叫 Lambda 函數以取得新使用者的隨機名稱的追蹤地圖\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-lambda-node.png) `random-name` 函數實作於 Node.js 中。它使用 Node.js 中適用於 JavaScript 的 SDK 來透過 Amazon SNS 傳送通知，並使用適用於 Node.js 的 X-Ray 開發套件來檢測 AWS SDK 用戶端。為寫入標註，函數會使用 `AWSXRay.captureFunc` 建立子區段，然後在受檢測函數中寫入標註。在 Lambda 中，您無法將註釋直接寫入函數區段，只能寫入您建立的子區段。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray/function/index.js) -- 隨機名稱 Lambda 函數** ``` var AWSXRay = require('aws-xray-sdk-core'); var AWS = AWSXRay.captureAWS(require('aws-sdk')); AWS.config.update({region: process.env.AWS_REGION}); var Chance = require('chance'); var myFunction = function(event, context, callback) { var sns = new AWS.SNS(); var chance = new Chance(); var userid = event.userid; var name = chance.first(); AWSXRay.captureFunc('annotations', function(subsegment){ subsegment.addAnnotation('Name', name); subsegment.addAnnotation('UserID', event.userid); }); // Notify var params = { Message: 'Created randon name "' + name + '"" for user "' + userid + '".', Subject: 'New user: ' + name, TopicArn: process.env.TOPIC_ARN }; sns.publish(params, function(err, data) { if (err) { console.log(err, err.stack); callback(err); } else { console.log(data); callback(null, {"name": name}); } }); }; exports.handler = myFunction; ``` 此函數會在您將簡易應用程式部署到 Elastic Beanstalk 時自動建立。`xray` 分支包含用來建立空白 Lambda 函數的指令碼。`.ebextensions` 資料夾中的組態檔案會在部署`npm install`期間使用 建置函數套件，然後使用 CLI 更新 Lambda AWS 函數。 ## 工作程序 受檢測工作者函數會在自己的分支 (`xray-worker`) 中提供，因為除非您先建立工作者函數及相關資源，否則它便無法執行。如需說明，請參閱[分支讀我檔案](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/README.md)。 該函數由綁定的 Amazon CloudWatch Events 事件每 5 分鐘觸發一次。執行時，函數會從 Scorekeep 管理的 Amazon SQS 佇列中提取項目。每個訊息都包含完整遊戲的相關資訊。 工作者會從遊戲記錄參考的其他資料表提取遊戲記錄及文件。例如，DynamoDB 中的遊戲記錄包含遊戲期間執行的移動清單。清單不包含移動本身，但包含存放在單獨資料表中移動的 ID。 工作階段及狀態也會以參考存放。這可避免遊戲資料表中的項目過大，但需要額外的呼叫才能取得所有遊戲相關資訊。工作者會解譯所有這些項目，並在 Amazon S3 中建構遊戲的完整記錄做為單一文件。當您想要對資料進行分析時，可以使用 Amazon Athena 直接在 Amazon S3 中對其執行查詢，而無需執行讀取密集型資料遷移，以從 DynamoDB 取得您的資料。 Amazon Athena ![\[顯示 scorekeep 工作者函數如何使用 Amazon SQS、Amazon S3 和 scorekeep API 的追蹤地圖。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-lambdaworker-node.png) 工作者函數在其位於 AWS Lambda內的組態中已啟用主動式追蹤。與隨機名稱函數不同，工作者不會收到來自經檢測應用程式的請求，因此 AWS Lambda 不會收到追蹤標頭。透過主動追蹤，Lambda 會建立追蹤 ID 並做出抽樣決策。 適用於 Python 的 X-Ray 開發套件只是函數頂端的幾行，可匯入開發套件並執行其`patch_all`函數，以修補用來呼叫 Amazon SQS 適用於 Python (Boto) 的 AWS SDK 和 Amazon S3 的 和 HTTclients。工作者呼叫 Scorekeep API 時，軟體開發套件會將[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)新增至請求，來追蹤透過 API 進行的呼叫。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray-worker/_lambda/scorekeep-worker/scorekeep-worker.py) -- 工作者 Lambda 函數** ``` import os import boto3 import json import requests import time from aws_xray_sdk.core import xray_recorder from aws_xray_sdk.core import patch_all patch_all() queue_url = os.environ['WORKER_QUEUE'] def lambda_handler(event, context): # Create SQS client sqs = boto3.client('sqs') s3client = boto3.client('s3') # Receive message from SQS queue response = sqs.receive_message( QueueUrl=queue_url, AttributeNames=[ 'SentTimestamp' ], MaxNumberOfMessages=1, MessageAttributeNames=[ 'All' ], VisibilityTimeout=0, WaitTimeSeconds=0 ) ... ``` # 檢測啟動程式碼 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 適用於 Java 的 X-Ray 開發套件會自動為傳入的請求建立區段。只要請求是在範圍內，您即可使用經檢測的用戶端並記錄子區段，而不會出現問題。如果您嘗試在啟動程式碼中使用經檢測的用戶端，則會收到 [SegmentNotFoundException](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/exceptions/SegmentNotFoundException.html)。 啟動程式碼會在 Web 應用程式的標準請求/回應流程之外執行，因此您需要手動建立區段以檢測起始程式碼。Scorekeep 會在其 `WebConfig` 檔案中顯示啟動程式碼的檢測。Scorekeep 會在啟動期間呼叫 SQL 資料庫和 Amazon SNS。 ![\[Diagram showing client requests to Scorekeeper-init, which connects to SQL database and SNS.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-init.png) 預設`WebConfig`類別會為通知建立 Amazon SNS 訂閱。若要在使用 Amazon SNS 用戶端時提供 X-Ray 開發套件寫入的區段，Scorekeep 會在全域記錄器`endSegment`上呼叫 `beginSegment`和 。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/WebConfig.java#L49) – 啟動程式碼中的檢測 AWS SDK 用戶端** ``` AWSXRay.beginSegment("Scorekeep-init"); if ( System.getenv("NOTIFICATION_EMAIL") != null ){ try { Sns.createSubscription(); } catch (Exception e ) { logger.warn("Failed to create subscription for email "+ System.getenv("NOTIFICATION_EMAIL")); } } AWSXRay.endSegment(); ``` 在 `RdsWebConfig`Scorekeep 在連接 Amazon RDS 資料庫時使用的 中，組態也會為 SQL 用戶端建立區段，供 Hibernate 在啟動期間套用資料庫結構描述時使用。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/RdsWebConfig.java#L83) – 在啟動程式碼中檢測 SQL 資料庫用戶端** ``` @PostConstruct public void schemaExport() { EntityManagerFactoryImpl entityManagerFactoryImpl = (EntityManagerFactoryImpl) localContainerEntityManagerFactoryBean.getNativeEntityManagerFactory(); SessionFactoryImplementor sessionFactoryImplementor = entityManagerFactoryImpl.getSessionFactory(); StandardServiceRegistry standardServiceRegistry = sessionFactoryImplementor.getSessionFactoryOptions().getServiceRegistry(); MetadataSources metadataSources = new MetadataSources(new BootstrapServiceRegistryBuilder().build()); metadataSources.addAnnotatedClass(GameHistory.class); MetadataImplementor metadataImplementor = (MetadataImplementor) metadataSources.buildMetadata(standardServiceRegistry); SchemaExport schemaExport = new SchemaExport(standardServiceRegistry, metadataImplementor); AWSXRay.beginSegment("Scorekeep-init"); schemaExport.create(true, true); AWSXRay.endSegment(); } ``` `SchemaExport` 會自動執行，並使用 SQL 用戶端。由於用戶端已經過檢測，因此 Scorekeep 必須覆寫預設的實作，並提供呼叫用戶端時軟體開發套件使用的區段。 # 檢測指令碼 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 您也可以檢測不屬於您應用程式部分的程式碼。當 X-Ray 協助程式執行時，它會將收到的任何區段轉送至 X-Ray，即使它們不是由 X-Ray SDK 產生。Scorekeep 會使用自己的指令碼檢測在部署期間編譯應用程式的建置。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/build.sh) – 檢測組建指令碼** ``` SEGMENT=$(python bin/xray_start.py) gradle build --quiet --stacktrace &> /var/log/gradle.log; GRADLE_RETURN=$? if (( GRADLE_RETURN != 0 )); then echo "Gradle failed with exit status $GRADLE_RETURN" >&2 python bin/xray_error.py "$SEGMENT" "$(cat /var/log/gradle.log)" exit 1 fi python bin/xray_success.py "$SEGMENT" ``` [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_start.py)、[https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_error.py) 和 [https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py](https://github.com/awslabs/eb-java-scorekeep/tree/xray/bin/xray_success.py) 是簡易的 Python 指令碼，可建構區段物件，將它們轉換成 JSON 文件，並透過 UDP 傳送到精靈。如果 Gradle 建置失敗，您可以按一下 X-Ray 主控台追蹤地圖中的 **scorekeep-build** 節點來尋找錯誤訊息。 ![\[Diagram showing client connection to Scorekeep-build with average time of 14.6s and 0.07/min.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-builderror.png) ![\[Timeline view showing Scorekeep-build process with 14.6 second duration and warning icon.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-timeline-builderror.png) ![\[Error message showing build failure due to missing ElasticBeanstalkPlugin symbol in RdsWebConfig class.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-exception-builderror.png) # 檢測 Web 應用程式用戶端 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間表的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 在[https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito)分支中，Scorekeep 使用 Amazon Cognito 讓使用者建立 帳戶，並使用該帳戶登入，從 Amazon Cognito 使用者集區擷取其使用者資訊。當使用者登入時，Scorekeep 會使用 Amazon Cognito 身分集區來取得臨時 AWS 登入資料，以便與 搭配使用 適用於 JavaScript 的 AWS SDK。 Identity Pool 是設定為可讓登入的使用者將追蹤資料寫入 AWS X-Ray。Web 應用程式會使用這些登入資料來記錄登入使用者的 ID、瀏覽器路徑和用戶端對 Scorekeep API 的呼叫檢視。 大部分工作都會在名稱為 `xray` 的服務類別中完成。此服務類別提供產生必要識別符、建立進行中區段、完成區段，以及將區段文件傳送至 X-Ray API 的方法。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/xray.js) – 記錄和上傳客群** ``` ... service.beginSegment = function() { var segment = {}; var traceId = '1-' + service.getHexTime() + '-' + service.getHexId(24); var id = service.getHexId(16); var startTime = service.getEpochTime(); segment.trace_id = traceId; segment.id = id; segment.start_time = startTime; segment.name = 'Scorekeep-client'; segment.in_progress = true; segment.user = sessionStorage['userid']; segment.http = { request: { url: window.location.href } }; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); return segment; } service.endSegment = function(segment) { var endTime = service.getEpochTime(); segment.end_time = endTime; segment.in_progress = false; var documents = []; documents[0] = JSON.stringify(segment); service.putDocuments(documents); } service.putDocuments = function(documents) { var xray = new AWS.XRay(); var params = { TraceSegmentDocuments: documents }; xray.putTraceSegments(params, function(err, data) { if (err) { console.log(err, err.stack); } else { console.log(data); } }) } ``` 您可在資源服務的標頭和 `transformResponse` 函數中呼叫這些方法，而 Web 應用程式會使用這些資源服務來呼叫 Scorekeep API。若要在與 API 產生的區段相同的追蹤中包含用戶端區段，Web 應用程式必須在 X-Ray SDK 可以讀取的[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader) (`X-Amzn-Trace-Id`) 中包含追蹤 ID 和區段 ID。當經檢測的 Java 應用程式收到具有此標頭的請求時，適用於 Java 的 X-Ray 開發套件會使用相同的追蹤 ID，並讓來自 Web 應用程式用戶端的區段成為其區段的父系。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js](https://github.com/awslabs/eb-java-scorekeep/tree/xray-cognito/public/app/services.js) – 記錄角度資源呼叫和寫入追蹤標頭的區段** ``` var module = angular.module('scorekeep'); module.factory('SessionService', function($resource, api, XRay) { return $resource(api + 'session/:id', { id: '@_id' }, { segment: {}, get: { method: 'GET', headers: { 'X-Amzn-Trace-Id': function(config) { segment = XRay.beginSegment(); return XRay.getTraceHeader(segment); } }, transformResponse: function(data) { XRay.endSegment(segment); return angular.fromJson(data); }, }, ... ``` 產生的追蹤映射包含 Web 應用程式用戶端的節點。 ![\[\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-client.png) 如果追蹤包括 Web 應用程式的區段，即會顯示使用者在瀏覽器中看到的 URL (路徑開頭為 `/#/`)。未使用用戶端檢測時，您只會取得 Web 應用程式呼叫之 API 資源的 URL (路徑開頭為 `/api/`)。 ![\[\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-traces-client.png) # 在工作者執行緒中使用受檢測用戶端 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。建議您遷移至 OpenTelemetry。如需遷移至 OpenTelemetry 的詳細資訊，請參閱[從 X-Ray 檢測遷移至 OpenTelemetry 檢測](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 Scorekeep 使用工作者執行緒，在使用者獲勝時將通知發佈至 Amazon SNS。發佈通知所花費的時間比其餘合併的請求操作更長，但不會影響用戶端或使用者。因此，若要改善回應時間，以非同步方式執行任務是一種好方法。 不過，適用於 Java 的 X-Ray 開發套件不知道在建立執行緒時哪個區段處於作用中狀態。因此，當您嘗試在執行緒中使用經檢測的 適用於 Java 的 AWS SDK 用戶端時，它會擲回 `SegmentNotFoundException`，使執行緒當機。 **Example web-1.error.log** ``` Exception in thread "Thread-2" com.amazonaws.xray.exceptions.SegmentNotFoundException: Failed to begin subsegment named 'AmazonSNS': segment cannot be found. at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method) at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62) at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45) ... ``` 為了修正此問題，應用程式會使用 `GetTraceEntity`取得主執行緒中區段的參考，並`Entity.run()`安全地執行具有區段內容存取權的工作者執行緒程式碼。 **Example [https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70](https://github.com/awslabs/eb-java-scorekeep/tree/xray/src/main/java/scorekeep/MoveFactory.java#L70) – 將追蹤內容傳遞至工作者執行緒** ``` import [com.amazonaws.xray.AWSXRay](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRay.html); import [com.amazonaws.xray.AWSXRayRecorder](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/AWSXRayRecorder.html); import [com.amazonaws.xray.entities.Entity](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Entity.html); import [com.amazonaws.xray.entities.Segment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Segment.html); import [com.amazonaws.xray.entities.Subsegment](https://docs.aws.amazon.com/xray-sdk-for-java/latest/javadoc/com/amazonaws/xray/entities/Subsegment.html); ... Entity segment = recorder.getTraceEntity(); Thread comm = new Thread() { public void run() { segment.run(() -> { Subsegment subsegment = AWSXRay.beginSubsegment("## Send notification"); Sns.sendNotification("Scorekeep game completed", "Winner: " + userId); AWSXRay.endSubsegment(); } } ``` 由於請求現在會在呼叫 Amazon SNS 之前解決，因此應用程式會為執行緒建立單獨的子區段。這可防止 X-Ray 開發套件在記錄來自 Amazon SNS 的回應之前關閉區段。如果 Scorekeep 解決請求時未開啟任何子區段，Amazon SNS 的回應可能會遺失。 ![\[\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-workerthread.png) 如需多執行緒的詳細資訊，請參閱[在多執行緒應用程式之間傳遞區段內容](xray-sdk-java-multithreading.md)。