本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 在 中追蹤 Step Functions 請求資料 AWS X-Ray 您可以使用 [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)視覺化狀態機器的元件、識別效能瓶頸，以及對導致錯誤的請求進行故障診斷。您的狀態機器會將追蹤資料傳送至 X-Ray，而 X-Ray 會處理資料，以產生服務地圖和可搜尋的追蹤摘要。 為您的狀態機器啟用 X-Ray 後，您可以在可使用 X-Ray 的所有 AWS 區域中，追蹤在 Step Functions 中執行的請求。這為您提供整個 Step Functions 請求的詳細概觀。即使上游服務未傳遞追蹤 ID，Step Functions 仍會將追蹤傳送至 X-Ray 以用於狀態機器執行。您可以使用 X-Ray 服務映射來檢視請求的延遲，包括與 X-Ray 整合的任何 AWS 服務。您也可以設定抽樣規則，根據您指定的條件，告訴 X-Ray 要記錄哪些請求，以及以哪些抽樣率記錄。 未為您的狀態機器啟用 X-Ray 且上游服務未傳遞追蹤 ID 時，Step Functions 不會將追蹤傳送至 X-Ray 以進行狀態機器執行。不過，如果追蹤 ID 是由上游服務傳遞，則 Step Functions 會將追蹤傳送至 X-Ray 以進行狀態機器執行。 您可以在支援兩者的區域搭配 AWS X-Ray Step Functions 使用 。如需 [X-Ray](https://docs.aws.amazon.com/general/latest/gr/xray.html) 和 [Step Functions](https://docs.aws.amazon.com/general/latest/gr/step-functions.html) 的區域支援資訊，請參閱 Step Functions 和 X-Ray 端點和配額頁面。 **X-Ray 和 Step Functions 合併配額** 您可以將資料新增至追蹤最多七天，並查詢過去三十天的追蹤資料，也就是 X-Ray 存放追蹤資料的時間長度。您的追蹤將受到 X-Ray 配額的限制。除了其他配額之外，X-Ray 還為 Step Functions 狀態機器提供 100 KiB 的最低保證追蹤大小。如果向 X-Ray 提供超過 100 KiB 的追蹤資料，這可能會導致凍結的追蹤。如需 [X-Ray 其他配額的詳細資訊，請參閱 X-Ray 端點和配額](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)頁面的服務配額一節。 **重要** Step Functions 不支援[*透過分散式映射狀態*](state-map-distributed.md)啟動的子工作流程執行的 X-Ray 追蹤，因為很容易超過此類執行的[追蹤文件大小限制](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)。 **Topics** + [設定與組態](#xray-concept-create) + [概念](#xray-concepts) + [服務整合](#xray-concept-integrations) + [檢視 X-Ray 主控台](#xray-concept-tracing-details) + [檢視 Step Functions 的 X-Ray 追蹤資訊](#concepts-xray-tracing-events) + [追蹤](#concepts-xray-traces) + [服務地圖](#concepts-xray-tracing-overview) + [區段和子區段](#concepts-xray-tracing-segments) + [分析](#concepts-xray-tracing-analytics) + [Configuration](#concepts-xray-tracing-config) + [如果追蹤映射或服務映射中沒有資料該怎麼辦？](#concepts-xray-troubleshooting) ## 設定與組態 ### 建立狀態機器時啟用 X-Ray 追蹤 您可以在建立新狀態機器時啟用 X-Ray 追蹤，方法是在**指定詳細資訊**頁面上選取**啟用 X-Ray 追蹤**。 1. 開啟 [Step Functions 主控台](https://console.aws.amazon.com/states/home)，然後選擇**建立狀態機器**。 1. 在**選擇撰寫方法**頁面上，選擇適當的選項來建立您的狀態機器。如果您選擇**執行範例專案**，則無法在狀態機器建立期間啟用 X-Ray 追蹤，而且您將需要在狀態機器建立之後啟用 X-Ray 追蹤。如需在現有狀態機器中啟用 X-Ray 的詳細資訊，請參閱 [在現有狀態機器中啟用 X-Ray](#xray-concept-enable-existing)。 選擇**下一步**。 1. 在**指定詳細資訊**頁面上，設定您的狀態機器。 1. 選擇**啟用 X-Ray 追蹤**。 Step Functions 狀態機器現在會將追蹤傳送至 X-Ray 以進行狀態機器執行。 **注意** 如果您選擇使用現有的 IAM 角色，則應確保允許 X-Ray 寫入。如需所需許可的詳細資訊，請參閱下列主題。 ### 在 Step Functions AWS X-Ray 中使用 的 IAM 政策 若要啟用 X-Ray 追蹤，您需要具有適當許可的 IAM 政策來允許追蹤。如果您的狀態機器使用其他整合服務，您可能需要其他 IAM 政策。請參閱特定服務整合的 IAM 政策。 如果您為現有狀態機器啟用 X-Ray 追蹤，您必須確保新增具有足夠許可的政策來啟用 X-Ray 追蹤。 **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:PutTraceSegments", "xray:PutTelemetryRecords", "xray:GetSamplingRules", "xray:GetSamplingTargets" ], "Resource": [ "*" ] } ] } ``` ### 在現有狀態機器中啟用 X-Ray 若要在現有狀態機器中啟用 X-Ray： 1. 在 [Step Functions 主控台](https://console.aws.amazon.com/states/home)中，選取您要啟用追蹤的狀態機器。 1. 選擇**編輯**。 1. 選擇**啟用 X-Ray 追蹤**。 您將看到通知，告知您可能需要進行其他變更。 **注意** 當您為現有狀態機器啟用 X-Ray 時，您必須確保擁有授予 X-Ray 足夠執行追蹤許可的 IAM 政策。您可以手動新增或產生。如需詳細資訊，請參閱 的 IAM 政策一節[在 Step Functions AWS X-Ray 中使用 的 IAM 政策](#xray-iam)。 1. （選用） 為您的狀態機器自動產生新角色，以包含 X-Ray 許可。 1. 選擇**儲存**。 ### 設定 Step Functions 的 X-Ray 追蹤 當您第一次在啟用 X-Ray 追蹤的情況下執行狀態機器時，它會使用 X-Ray 追蹤的預設組態值。 AWS X-Ray 不會針對傳送至應用程式的每個請求收集資料。反之，它會收集統計上大量請求的資料。預設為每秒記錄第一個請求，以及任何額外請求的 5%。每秒一個請求是*儲槽*。這可確保只要服務持續提供請求，每秒都會記錄至少一個追蹤。5% 是超過儲槽大小的額外請求抽樣「速率」**。 為了避免開始使用時產生的服務費用，預設的抽樣費率都很保守。您可以設定 X-Ray 來修改預設抽樣規則，並根據服務或請求的屬性設定套用抽樣的其他規則。 例如，您可能想要停用取樣，並追蹤所有修改狀態或處理常式 AWS 帳戶 或交易的呼叫請求。對於大量唯讀呼叫，例如背景輪詢、運作狀態檢查或連線維護，您可以低速率取樣，但仍取得足夠的資料來觀察發生的問題。 若要設定狀態機器的取樣規則： 1. 前往 [X-Ray 主控台](https://console.aws.amazon.com/xray/home)。 1. 選擇**抽樣**。 1. 若要建立規則，請選擇 **Create sampling rule (建立抽樣規則)**。 若要編輯規則，請選擇規則的名稱。 若要刪除規則，請選擇規則並使用 **Actions (動作)** 功能表來刪除它。 無法變更現有抽樣規則的某些部分，例如名稱和優先順序。反之，請新增或複製現有的規則、進行您想要的變更，然後使用新的規則。 如需 X-Ray 取樣規則以及如何設定各種參數的詳細資訊，請參閱 [X-Ray 主控台中的設定取樣規則](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)。 ### 整合上游服務 若要整合 Step Functions 工作流程的執行，例如 Express、Synchronous 和 Standard 工作流程，以及設定 所需的上游服務`traceHeader`。如果您在 API Gateway 中使用 HTTP API，系統會自動為您執行此操作。不過，如果您使用的是 Lambda 函數和/或 SDK，則需要自行在 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html)或 [https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) API 呼叫`traceHeader`上設定 。 您必須將`traceHeader`格式指定為 `\p{ASCII}∗`。此外，若要讓 Step Functions 使用相同的追蹤 ID，您必須將格式指定為 `Root={TRACE_ID};Sampled={1 or 0}`。如果您使用的是 Lambda 函數，請將 取代`TRACE_ID`為目前區段中的追蹤 ID，並將取樣欄位設定為 `1` ，如同您的取樣模式為 true 且`0`您的取樣模式為 false。以此格式提供追蹤 ID，可確保您取得完整的追蹤。 以下是以 Python 撰寫的範例，示範如何指定 `traceHeader`。 ``` state_machine = config.get_string_paramter("STATE_MACHINE_ARN") if (xray_recorder.current_subsegment() is not None and xray_recorder.current_subsegment().sampled) : trace_id = "Root={};Sampled=1".format( xray_recorder.current_subsegment().trace_id ) else: trace_id = "Root=not enabled;Sampled=0" LOGGER.info("trace %s", trace_id) # execute it response = states.start_sync_execution( stateMachineArn=state_machine, input=event['body'], name=context.aws_request_id, traceHeader=trace_id ) LOGGER.info(response) ``` **X-Ray 標頭或承載中的追蹤** 對於 X-Ray 追蹤，所有 AWS 服務都會使用 HTTP 請求中的 `X-Amzn-Trace-Id`標頭。使用 標頭是識別追蹤的偏好機制。 `StartExecution`和 `StartSyncExecution` API 操作也可以`traceHeader`從請求承載的內文使用 。如果提供**這兩個**來源， Step Functions 將使用**標頭值** （偏好） 取代請求內文中的值。 ## 概念 ### X-Ray 主控台 在 AWS X-Ray 主控台中，您可以檢視應用程式在為狀態機器啟用 X-Ray 時所提供的請求的服務映射和追蹤。 [檢視 X-Ray 主控台](#xray-concept-tracing-details) 如需如何存取狀態機器執行的 X-Ray 主控台的詳細資訊，請參閱 。 如需 X-Ray 主控台的詳細資訊，請參閱 [X-Ray 主控台文件](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html)。 ### 區段、子區段和追蹤 **區段**會記錄您狀態機器請求的相關資訊。它包含 狀態機器執行的工作等資訊，也可能包含包含下游呼叫相關資訊**的子區段**。 **追蹤**會收集單一請求所產生的所有區段。 ### 抽樣 為了確保有效率的追蹤並提供應用程式提供的請求代表性範例，X-Ray 會套用**取樣**演算法來判斷要追蹤哪些請求。這可以透過編輯抽樣規則來變更。 ### 指標 對於您的狀態機器，X-Ray 將測量調用時間、狀態轉換時間、Step Functions 的整體執行時間和在此執行時間中的變異。您可以透過 X-Ray 主控台存取此資訊。 ### 分析 AWS X-Ray Analytics 主控台是一種互動式工具，可用來解譯追蹤資料。您可以按一下與目前追蹤集相關聯之指標和欄位的圖表和面板，使用愈益精細的篩選條件來精簡作用中的資料集。您可以分析狀態機器的效能，以找出並識別效能問題。 如需 X-Ray 分析的詳細資訊，請參閱[與 AWS X-Ray Analytics 主控台互動](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-analytics.html) ## Step Functions 服務整合和 X-Ray 與 Step Functions 整合的一些 AWS 服務 AWS X-Ray 透過將追蹤標頭新增至請求、執行 X-Ray 協助程式，或進行抽樣決策，以及將追蹤資料上傳至 X-Ray，來提供與 的整合。其他 必須使用 AWS X-Ray SDK 進行檢測。其中一些尚不支援 X-Ray 整合。使用與 Step Functions 的服務整合時，X-Ray 整合是提供完整追蹤資料的必要項目 ### 原生 X-Ray 支援 與原生 X-Ray 支援的服務整合包括： + [Amazon Simple Notification Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html) + [Amazon Simple Queue Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sqs.html) + [AWS Lambda](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html) + AWS Step Functions ### 需要檢測 需要 [X-Ray 檢測](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)的服務整合： + Amazon Elastic Container Service + AWS Batch + AWS Fargate ### 僅限用戶端追蹤 其他服務整合不支援 X-Ray 追蹤。不過，仍然可以收集用戶端追蹤： + Amazon DynamoDB + Amazon EMR + Amazon SageMaker AI + AWS CodeBuild + AWS Glue ## 檢視 X-Ray 主控台 X-Ray 以區段形式接收來自 服務的資料。X-Ray 會將具有常見請求的區段分組為追蹤。X-Ray 會處理追蹤，以產生服務圖表，以視覺化方式呈現您的應用程式。 啟動狀態機器的執行後，您可以在**執行詳細資訊**區段中選擇 X-Ray 追蹤**映射連結，以檢視其 X-Ray 追蹤**。 為狀態機器啟用 X-Ray 之後，您可以在 X-Ray 主控台中檢視其執行的追蹤資訊。 ## 檢視 Step Functions 的 X-Ray 追蹤資訊 下列步驟說明在啟用 X-Ray 並執行執行之後，您可以在 主控台中看到哪些資訊。[使用 Amazon SQS、Amazon SNS 和 Lambda 建立回呼模式範例](callback-task-sample-sqs.md) 範例專案的 X-Ray 追蹤隨即顯示。 ## 追蹤 執行完成後，您可以導覽至 X-Ray 主控台，您將在其中看到 X-Ray **追蹤**頁面。這會顯示服務映射的概觀，以及狀態機器的追蹤和區段資訊。 ![\[狀態機器 X-Ray 追蹤的說明性螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/xray-tracing-overview.png) ## 服務地圖 X-Ray 主控台中的服務映射可協助您識別發生錯誤的服務、具有高延遲連線的服務，或查看失敗請求的追蹤。 ![\[聚焦於 X-Ray 追蹤中服務映射的說明性螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/xray-tracing-servicemap.png) 在追蹤映射上，您可以選擇服務節點來檢視該節點的請求，或選擇兩個節點之間的邊緣來檢視已通過該連線的請求。在這裡，已選取`WaitForCallBack`節點，您可以檢視其執行和回應狀態的其他資訊。 ![\[X-Ray 追蹤節點的範例詳細資訊。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/xray-tracing-servicemap-detail.png) 您可以查看 X-Ray 服務映射如何與狀態機器相關聯。Step Functions 會呼叫每個服務整合的服務映射節點，只要它支援 X-Ray。 ![\[追蹤狀態機器的範例圖形表示法。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/sample-callback-example.png) ## 區段和子區段 **追蹤**是由單一請求產生的**區段**集合。每個區段都會提供資源的名稱、請求的詳細資訊，以及已完成工作的詳細資訊。在**追蹤**頁面上，您可以看到區段，如果展開，您可以看到其對應的子區段。您可以選擇區段或子區段來檢視其詳細資訊。 您將成為服務地圖上每個節點的不同客群。 ![\[狀態機器區段和子區段的範例螢幕擷取畫面。\]](http://docs.aws.amazon.com/zh_tw/step-functions/latest/dg/images/xray-tracing-segments.png) 選擇客群可提供資源的名稱、請求的詳細資訊，以及已完成工作的詳細資訊。 區段可以將完成工作的資料細分為子區段。選擇子區段會顯示精細的時間資訊和詳細資訊。子區段可以包含有關呼叫 AWS 服務、外部 HTTP API 或 SQL 資料庫的其他詳細資訊。 ## 分析 AWS X-Ray **Analytics** 主控台是解譯追蹤資料的互動式工具。您可以使用此功能，更輕鬆地了解狀態機器的效能。您可以透過互動式回應時間和時間序列圖表來探索、分析和視覺化追蹤，以協助找出效能和延遲問題。 您可以按一下與目前追蹤集相關聯之指標和欄位的圖表和面板，使用愈益精細的篩選條件來精簡作用中的資料集。 ## Configuration 您可以從 X-Ray 主控台設定取樣和加密選項。 + 選擇**取樣**以檢視取樣率和組態的詳細資訊。 您可以變更抽樣規則來控制記錄的資料量，並修改抽樣行為以符合您的特定需求。 + 選擇**加密**以修改加密設定。 您可以使用預設設定，其中 X-Ray 會加密靜態追蹤和資料，或者視需要選擇 KMS 金鑰。標準[AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/)費用適用於後一種情況。 ## 如果追蹤映射或服務映射中沒有資料該怎麼辦？ 如果您已啟用 X-Ray，但無法在 X-Ray 主控台中看到任何資料，請檢查： + 您的 IAM 角色已正確設定，以允許寫入 X-Ray。 + 抽樣規則允許抽樣資料。 + 由於在套用新建立或修改的 IAM 角色之前可能會有短暫的延遲，請在幾分鐘後再次檢查追蹤或服務映射。 + 如果您在 X-Ray 追蹤面板中看到**找不到資料**，請檢查您的 [IAM 帳戶設定](https://console.aws.amazon.com/iam/home?#/account_settings)，並確保 AWS Security Token Service 已針對預期區域啟用 。如需詳細資訊，請參閱《*IAM 使用者指南*》中的在 [AWS STS 中啟用和停用 AWS 區域](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate) 。