本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 在 Step Functions 中檢視 X-Ray 追蹤
在本教學課程中，您將了解如何使用 X-Ray 追蹤執行狀態機器時發生的錯誤。您可以使用 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)視覺化狀態機器的元件、識別效能瓶頸，以及對導致錯誤的請求進行故障診斷。在本教學課程中，您將建立數個 Lambda 函數來隨機產生錯誤，然後您可以使用 X-Ray 追蹤和分析。
本[建立使用 Lambda 的 Step Functions 狀態機器](tutorial-creating-lambda-state-machine.md)教學課程會逐步引導您建立呼叫 Lambda 函數的狀態機器。如果您已完成該教學課程，請跳至[步驟 2](#create-xray-lambda-state-machine-step-4)，並使用您先前建立的 AWS Identity and Access Management (IAM) 角色。
## 步驟 1：建立 Lambda 的 IAM 角色
AWS Lambda 和 AWS Step Functions 都可以執行程式碼和存取 AWS 資源 （例如，存放在 Amazon S3 儲存貯體中的資料）。若要維護安全性，您必須授予 Lambda 和 Step Functions 對這些資源的存取權。
Lambda 要求您在建立 Lambda 函數時指派 AWS Identity and Access Management (IAM) 角色，就像 Step Functions 要求您在建立狀態機器時指派 IAM 角色一樣。
### 建立角色以搭配 Lambda 使用
您可以使用 IAM 主控台來建立服務連結角色。
**建立角色 (主控台)**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 的 IAM 主控台。
1. 在 IAM 主控台的導覽窗格中，選擇 **Roles** (角色)。然後選擇 **Create role** (建立角色)。
1. 選擇**AWS 服務**角色類型，然後選擇 **Lambda**。
1. 選擇 **Lambda** 使用案例。服務會定義使用案例，以包含服務所需的信任政策。然後選擇 **Next: Permissions** (下一步：許可)。
1. 選擇一或多個許可政策以連接至角色 (例如 `AWSLambdaBasicExecutionRole`)。請參閱 [AWS Lambda 許可模型](https://docs.aws.amazon.com/lambda/latest/dg/intro-permission-model.html)。
選取可指派您要角色具有之許可政策旁的方塊，然後選擇 **Next: Review (下一步：檢閱)**。
1. 輸入 **Role name (角色名稱)**。
1. (選擇性) 針對 **Role description (角色描述)**，編輯新服務連結角色的描述。
1. 檢閱角色，然後選擇 **Create role** (建立角色)。
## 步驟 2：建立 Lambda 函數
您的 Lambda 函數會隨機擲出錯誤或逾時，產生範例資料以在 X-Ray 中檢視。
**重要**
確保您的 Lambda 函數與 AWS 區域 狀態機器位於相同的 AWS 帳戶下。
1. 開啟 [Lambda 主控台](https://console.aws.amazon.com/lambda/home)，然後選擇**建立函數**。
1. 在 **Create function (建立函數)** 區段中，選擇 **Author from scratch (從頭開始撰寫)**。
1. 在**基本資訊**區段中，設定您的 Lambda 函數：
1. 針對**函數名稱**，請輸入 `TestFunction1`。
1. 在**執行期**選擇 **Node.js 18.x**。
1. 針對 **Role (角色)**，請選擇 **Choose an existing role (選擇現有的角色)**。
1. 針對**現有角色**，選取[您先前建立的 Lambda 角色](#create-xray-lambda-state-machine-to-create-a-role-for-use-with-lambda)。
**注意**
如果您建立的 IAM 角色未出現在清單中，則角色仍可能需要幾分鐘的時間才能傳播至 Lambda。
1. 選擇**建立函數**。
建立 Lambda 函數時，請注意頁面右上角的 Amazon Resource Name (ARN)。例如：
```
arn:aws:lambda:region:123456789012:function:TestFunction1
```
1. 將 Lambda 函數的下列程式碼複製到 ***TestFunction1*** 頁面的**函數程式碼**區段。
```
function getRandomSeconds(max) {
return Math.floor(Math.random() * Math.floor(max)) * 1000;
}
function sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
export const handler = async (event) => {
if(getRandomSeconds(4) === 0) {
throw new Error("Something went wrong!");
}
let wait_time = getRandomSeconds(5);
await sleep(wait_time);
return { 'response': true }
};
```
此程式碼會隨機建立定時失敗，這將用於在狀態機器中產生範例錯誤，您可以使用 X-Ray 追蹤來檢視和分析這些錯誤。
1. 選擇**儲存**。
## 步驟 3：建立另外兩個 Lambda 函數
建立另外兩個 Lambda 函數。
1. 重複步驟 2 以建立另外兩個 Lambda 函數。對於下一個函數，在**函數名稱**中，輸入 `TestFunction2`。對於最後一個函數，在**函數名稱**中，輸入 `TestFunction3`。
1. 在 Lambda 主控台中，確認您現在有三個 Lambda 函數 `TestFunction1`、 `TestFunction2`和 `TestFunction3`。
## 步驟 4：建立狀態機器
在此步驟中，您將使用 [Step Functions 主控台](https://console.aws.amazon.com/states/home?region=us-east-1#/)建立具有三個狀態的狀態機器`Task`。每個`Task`狀態都會參考三個 Lambda 函數的其中一個。
1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home)，從功能表中選擇**狀態機器**，然後選擇**建立狀態機器**。
**重要**
請確定您的狀態機器與您先前在[步驟 2](#create-xray-lambda-state-machine-step-2) 和[步驟 3](#create-xray-lambda-state-machine-step-3) 中建立的 Lambda 函數位於相同的 AWS 帳戶和區域。
1. 選擇**從空白建立**。
1. 為您的狀態機器命名，然後選擇**繼續**在 Workflow Studio 中編輯您的狀態機器。
1. 在本教學課程中，您將在 中撰寫狀態機器的 [Amazon States Language](concepts-amazon-states-language.md)(ASL) 定義[程式碼編輯器](workflow-studio.md#wfs-interface-code-editor)。若要這樣做，請選擇**程式碼**。
1. 移除現有的樣板程式碼並貼上下列程式碼。在任務狀態定義中，請記得將範例 ARNs 取代為您建立的 Lambda 函數ARNs。
```
{
"StartAt": "CallTestFunction1",
"States": {
"CallTestFunction1": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:test-function1",
"Catch": [
{
"ErrorEquals": [
"States.TaskFailed"
],
"Next": "AfterTaskFailed"
}
],
"Next": "CallTestFunction2"
},
"CallTestFunction2": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:test-function2",
"Catch": [
{
"ErrorEquals": [
"States.TaskFailed"
],
"Next": "AfterTaskFailed"
}
],
"Next": "CallTestFunction3"
},
"CallTestFunction3": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:123456789012:function:test-function3",
"TimeoutSeconds": 5,
"Catch": [
{
"ErrorEquals": [
"States.Timeout"
],
"Next": "AfterTimeout"
},
{
"ErrorEquals": [
"States.TaskFailed"
],
"Next": "AfterTaskFailed"
}
],
"Next": "Succeed"
},
"Succeed": {
"Type": "Succeed"
},
"AfterTimeout": {
"Type": "Fail"
},
"AfterTaskFailed": {
"Type": "Fail"
}
}
}
```
這是使用 Amazon States Language 的狀態機器描述。它定義三個名為 `CallTestFunction1`、 `CallTestFunction2`和 `Task`的狀態`CallTestFunction3`。每個 會呼叫三個 Lambda 函數的其中之一。如需詳細資訊，請參閱[狀態機器結構](statemachine-structure.md)。
1. 為您的狀態機器指定名稱。若要這樣做，請選擇 **MyStateMachine** 預設狀態機器名稱旁的編輯圖示。然後，在**狀態機器組態**中，在**狀態機器名稱方塊中指定名稱**。
針對本教學課程，輸入名稱 **TraceFunctions**。
1. （選用） 在**狀態機器組態**中，指定其他工作流程設定，例如狀態機器類型及其執行角色。
在此教學課程中，在其他**組態**下，選擇**啟用 X-Ray 追蹤**。在**狀態機器設定**中保留所有其他預設選擇。
如果您[先前已建立具有狀態機器正確許可的 IAM 角色](procedure-create-iam-role.md)，並想要使用它，請在**許可**中，選取**選擇現有角色**，然後從清單中選擇角色。或選取**輸入角色 ARN**，然後為該 IAM 角色提供 ARN。
1. 在**確認角色建立**對話方塊中，選擇**確認**以繼續。
您也可以選擇**檢視角色設定**以返回**狀態機器組態**。
**注意**
如果您刪除 Step Functions 建立的 IAM 角色，Step Functions 稍後無法重新建立該角色。同樣地，如果您修改角色 （例如，從 IAM 政策中的主體移除 Step Functions)，Step Functions 稍後無法還原其原始設定。
## 步驟 5：執行狀態機器
狀態機器執行是您執行工作流程以執行任務的執行個體。
1. 在 ***TraceFunctions*** 頁面上，選擇**開始執行**。
系統會隨即顯示 **New execution (新執行)** 頁面。
1. 在**開始執行**對話方塊中，執行下列動作：
1. （選用） 輸入自訂執行名稱以覆寫產生的預設值。
**非 ASCII 名稱和記錄**
Step Functions 接受包含非 ASCII 字元的狀態機器、執行、活動和標籤名稱。由於這類字元會阻止 Amazon CloudWatch 記錄資料，我們建議您僅使用 ASCII 字元，以便您可以追蹤 Step Functions 指標。
1. 選擇 **Start execution (開始執行)**。
1. Step Functions 主控台會引導您前往標題為您的執行 ID 的頁面。此頁面稱為*執行詳細資訊*頁面。在此頁面上，您可以在執行進行時或完成後檢閱執行結果。
若要檢閱執行結果，請在**圖形檢視**中選擇個別狀態，然後選擇[步驟詳細資訊](concepts-view-execution-details.md#exec-details-intf-step-details)窗格上的個別索引標籤，分別檢視每個狀態的詳細資訊，包括輸入、輸出和定義。如需您可以在執行詳細資訊頁面上檢視之*執行資訊的詳細資訊*，請參閱 [執行詳細資訊概觀](concepts-view-execution-details.md#exec-details-interface-overview)。
執行數個 （至少三個） 執行。
1. 執行完成後，請遵循 **X-Ray 追蹤映射**連結。您可以在執行仍在執行時檢視追蹤，但建議您先查看執行結果，再檢視 X-Ray 追蹤映射。
1. 檢視服務映射以識別發生錯誤的位置、具有高延遲的連線，或追蹤失敗的請求。在此範例中，您可以查看每個函數接收的流量。 `TestFunction2` 的呼叫頻率超過 `TestFunction3`，而且`TestFunction1`呼叫的頻率超過 的兩倍`TestFunction2`。
服務映射會透過根據成功呼叫與錯誤及故障的比例，將每個節點標上顏色，來指出每個節點的運作狀態。
+ **綠色**表示成功呼叫
+ **紅色**表示伺服器故障 (500 系列錯誤)
+ **黃色**表示用戶端錯誤 (400 系列錯誤)
+ **紫色**表示調節錯誤 (429 請求數太多)
![\[三個測試函數的 X-Ray 追蹤節點範例螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/tutorial-xray-service.png)
您也可以選擇服務節點來檢視該節點的請求，或選擇兩個節點之間的邊緣來檢視已通過該連線的請求。
1. 檢視 X-Ray 追蹤映射，以查看每次執行發生的情況。Timeline (時間表) 檢視會顯示區段和子區段的階層。清單中的第一個項目是區段，代表服務為單一請求記錄的所有資料。在區段下方為子區段。此範例顯示 Lambda 函數記錄的子區段。
![\[測試函數的 X-Ray 時間軸區段和子區段的說明性範例螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/tutorial-xray-trace.png)
如需了解 X-Ray 追蹤和搭配 Step Functions 使用 X-Ray 的詳細資訊，請參閱 [在 中追蹤 Step Functions 請求資料 AWS X-Ray](concepts-xray-tracing.md)