本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
開始使用記分範例應用程式
本教學課程使用 Scorekeep 範例應用程式的xray-gettingstarted分支，該應用程式用 AWS CloudFormation 於建立和設定在 Amazon ECS 上執行範例應用程式和 X-Ray 精靈的資源。此應用程式會使用 Spring 架構來實作 JSON 網頁 API，並將資料保留 AWS SDK for Java 至 Amazon DynamoDB。應用程式中的 Servlet 篩選器會檢測應用程式提供的所有傳入請求，以及 AWS SDK 用戶端上的要求處理常式會向 DynamoDB 進行下游呼叫。
您可以使用 AWS Management Console 或遵循本自學課程 AWS CLI。
章節
必要條件
本教學課程用 AWS CloudFormation 於建立和設定執行範例應用程式和 X-Ray 精靈的資源。在教學課程中安裝和執行需要下列先決條件：
-
如果您使用具有有限許可的 IAM 使用者，請在 IAM 主控台
中新增以下使用者政策： -
AWSCloudFormationFullAccess— 訪問和使用 CloudFormation -
AmazonS3FullAccess-將模板文件上傳到 CloudFormation使用 AWS Management Console -
IAMFullAccess— 創建 Amazon ECS 和 Amazon EC2 實例角色 -
AmazonEC2FullAccess— 創建 Amazon EC2 資源 -
AmazonDynamoDBFullAccess— 建立動 DynamoDB 料表 -
AmazonECS_FullAccess— 創建 Amazon ECS 資源 -
AmazonSNSFullAccess— 創建 Amazon SNS 主題 -
AWSXrayReadOnlyAccess— 允許在 X-Ray 控制台中查看跟踪圖和痕跡
-
-
若要使用執行教學課程 AWS CLI，請安裝 CLI 2.7.9 版或更新版本，並使用上一個步驟中的使用者設定 CLI。使用使用者進行設定時，請確定已 AWS CLI 設定區域。如果未設定區域，您將需要附加
--region至每個 CLI 命令。AWS-REGION -
請確定已安裝 Git
，以便複製範例應用程式存放庫。 -
使用下列程式碼範例來複製 Scorekeep 儲存庫的
xray-gettingstarted分支：git clone https://github.com/aws-samples/eb-java-scorekeep.git xray-scorekeep -b xray-gettingstarted
使用下列方式安裝記分應用程式 CloudFormation
產生追蹤資料
範例應用程式包含前端 Web 應用程式。使用 Web 應用程式產生 API 的流量，並將追蹤資料傳送至 X-Ray。首先，使用 AWS Management Console 或來擷取 Web 應用程式 URL AWS CLI：
使用 Web 應用程式產生追蹤資料
-
選擇 Create (建立) 來產生使用者及工作階段。
-
輸入 game name (遊戲名稱)、將 Rules (規則) 設為 Tic Tac Toe (井字遊戲)，然後選擇 Create (建立)。
-
選擇 Play (遊玩) 來啟動遊戲。
-
選擇一個磚來進行移動並變更遊戲狀態。
這些步驟中的每個步驟都會產生 API 的 HTTP 請求，並對 DynamoDB 產生下游呼叫，以讀取和寫入使用者、工作階段、遊戲、移動和狀態資料。
在「」中檢視軌跡圖 AWS Management Console
您可以在 X-Ray 和 CloudWatch 主控台中查看範例應用程式產生的軌跡圖和軌跡。
原因指出在 WebConfig 類別中對 createSubscription 發出的呼叫內所提供的電子郵件地址無效。在下一節中，我們將修正此問題。
設定 Amazon SNS 通知
記分保持使用者完成遊戲時，會使用 Amazon SNS 傳送通知。當應用程式啟動時，它會嘗試為 CloudFormation 堆疊參數中定義的電子郵件地址建立訂閱。該呼叫目前失敗。設定通知電子郵件以啟用通知，並解決追蹤對映中反白顯示的失敗項目。
更新完成時，Scorekeep 會重新啟動並建立 SNS 主題訂閱。檢查您的電子郵件以確認訂閱，在您完成遊戲時查看更新。開啟追蹤對應，確認對 SNS 的呼叫不再失敗。
探索範例應用程式
範例應用程式是 Java 中的 HTTP 網頁 API，其設定為使用適用於 Java 的 X-Ray SDK。當您使用 CloudFormation 範本部署應用程式時，它會建立 DynamoDB 表、Amazon ECS 叢集，以及在 ECS 上執行記分所需的其他服務。ECS 的任務定義檔案是透過 CloudFormation建立的。此檔案定義 ECS 叢集中每項工作所使用的容器映像。這些圖像是從官方 X-Ray 公共 ECR 獲得的。得分保持 API 容器映像具有使用搖籃編譯的 API。Scorekeep 前端容器的容器映像使用 nginx 代理服務器為前端提供服務。此伺服器會將要求路由傳送至以 /api 開頭的路徑至 API。
為了檢測傳入 HTTP 請求，應用程式會新增軟體開發套件提供的 TracingFilter。
範例 src /主/爪/記分/. Java-服務程序過濾器 WebConfig
import javax.servlet.Filter;
import com.amazonaws.xray.javax.servlet.AWSXRayServletFilter;
...
@Configuration
public class WebConfig {
@Bean
public Filter TracingFilter() {
return new AWSXRayServletFilter("Scorekeep");
}
...此篩選條件會傳送應用程式處理的所有傳入請求相關追蹤資料，包括請求 URL、方法、回應狀態、開始時間及結束時間。
此應用程式也會使用. AWS SDK for Java為了測量這些調用，應用程序只需將 AWS SDK 相關的子模塊作為依賴關係，Java 的 X-Ray SDK 會自動檢測所有 AWS SDK 客戶端。
該應用程序Docker使用與Gradle Docker Image和Scorekeep API Dockerfile文件實例構建源代碼，以運行 Gradle 在其中生成的可執行 JAR。ENTRYPOINT
範例 使用碼頭通過搖籃碼頭圖像構建
docker run --rm -v /PATH/TO/SCOREKEEP_REPO/home/gradle/project -w /home/gradle/project gradle:4.3 gradle build範例 碼頭檔入口點
ENTRYPOINT [ "sh", "-c", "java -Dserver.port=5000 -jar scorekeep-api-1.0.0.jar" ]build.gradle 檔案會在編譯期間，透過將其宣告為依存項目，來從 Maven 下載軟體開發套件子模組。
範例 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 儀器子模組都是自動檢測使用 SDK 進行的任何下游呼叫所需的全部功能。 AWS
若要將原始區段資料轉送至 X-Ray API，X-Ray 精靈需要監聽 UDP 連接埠 2000 上的流量。為此，應用程序將 X-Ray 守護程序在一個容器中運行，該容器與 ECS 上的 Scorekeep 應用程序一起部署為附屬容器。如需詳細資訊，請查看 X-Ray 精靈主題。
範例 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 SDK 提供了一個名為的類AWSXRay，它提供了全局記錄器TracingHandler，您可以使用它來檢測代碼。您可以設定全域記錄器來自訂為傳入 HTTP 呼叫建立區段的 AWSXRayServletFilter。範例包括 WebConfig 類別中的靜態區塊，該區塊會使用外掛程式和抽樣規則設定全域記錄器。
範例 src /主/爪/記分/ .java-記錄器 WebConfig
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 的檔案載入抽樣規則。抽樣規則會判斷軟體開發套件記錄傳入請求區段的速率。
範例 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 範例應用。
選用：最低權限政策
Scorekeep ECS 容器會使用完整存取原則 (例如和) 存取資源。AmazonSNSFullAccess AmazonDynamoDBFullAccess使用完整存取原則不是生產應用程式的最佳作法。下列範例會更新 DynamoDB 身分與存取權管理政策，以改善應用程式的安全性。若要進一步了解 IAM 政策中的安全最佳實務，請參閱 AWS X-Ray 的身分識別與存取管理。
範例 CF-資源管理模板 ECS 定義 TaskRole
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。最後，您將該政策套用至您的執行個體設定檔。
若要識別動態資源的 ARN，請執行下列動作：
-
開啟 DynamoDB 主控台
。 -
從左側導覽列選擇 [表格]。
-
選擇任一項
scorekeep-*來顯示表格詳細資訊頁面。 -
在 [概觀] 索引標籤下，選擇 [其他資訊] 以展開區段並檢視 Amazon 資源名稱 (ARN)。複製這個值。
-
將 ARN 插入下列 IAM 政策，並以您的特定區域
AWS_REGION和帳戶 ID 取代和AWS_ACCOUNT_ID值。這個新策略只允許指定的處理行動，而不允許任何動作的AmazonDynamoDBFullAccess策略。{ "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:<AWS_REGION>:<AWS_ACCOUNT_ID>:table/scorekeep-*" } ] }應用程式建立的資料表遵循一致的命名慣例。您可以使用此
scorekeep-*格式來表示所有「計分保留」表格。
變更您的 IAM 政策
-
從 IAM 主控台開啟記分任務角色 (記分
項目)。 -
選擇
AmazonDynamoDBFullAccess策略旁邊的核取方塊，然後選擇 [移除] 以移除此原則。 -
選擇 [新增權限]，然後選取 [附加原則]，最後選取 [建立原則
-
選擇 JSON 選項卡並粘貼到上面創建的策略中。
-
選擇下一步:頁面底部的標籤。
-
選擇「下一步」：頁面底部的「檢閱」。
-
對於名稱，指定策略的名稱。
-
選擇頁面底部的 [建立原則]。
-
將新建立的原則附加至
scorekeepRole角色。附加的原則可能需要幾分鐘的時間才會生效。
如果您已將新原則附加至scorekeepRole角色，則必須先將其中斷連結，然後再刪除 CloudFormation 堆疊，因為此連結的原則會封鎖堆疊遭到刪除。可透過刪除原則來自動卸離原則。
移除您的自訂 IAM 政策
-
開啟 IAM 主控台
。 -
從左側導覽列選擇「策略」。
-
搜尋您先前在本節中建立的自訂原則名稱，然後選擇原則名稱旁邊的圓鈕將其反白顯示。
-
選擇動作下拉式清單，然後選擇刪除。
-
輸入自訂原則的名稱，然後選擇 [刪除] 以確認刪除。這會自動將原則與
scorekeepRole角色中斷連結。
清除
請依照下列步驟刪除「記分」應用程式資源：
注意
如果您使用本教學課程的前一節建立並附加自訂原則，則必須先從中移除原則，scorekeepRole然後再刪除 CloudFormation 堆疊。
後續步驟
在下一章中了解有關 X-Ray 的更多信息，AWS X-Ray 概念.
要檢測您自己的應用程序，請進一步了解 Java 的 X-Ray SDK 或其他 X-Ray SDK 之一：
-
適用於 Java 的 X-Ray SDK — 適用於 Java 的AWS X-Ray SDK
-
適用於 Node.js 的 X-Ray SDK — AWS Node.js SDK 的 X-Ray 護理
-
適用於. NET 的 X-Ray SDK — AWS X-Ray SDK for .NET
若要在本機或上執行 X-Ray 精靈 AWS，請參閱AWS X-Ray 守護進。
若要參閱上的範例應用程式 GitHub，請參閱eb-java-scorekeep
