本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS X-Ray 概念 AWS X-Ray 從 服務接收資料做為*區段*。然後，X-Ray 會將具有常見請求的客群分組為*追蹤*。X-Ray 會處理追蹤，以產生*服務圖表*，提供應用程式的視覺化呈現。 **Topics** + [客群](#xray-concepts-segments) + [子區段](#xray-concepts-subsegments) + [服務圖表](#xray-concepts-servicegraph) + [追蹤](#xray-concepts-traces) + [抽樣](#xray-concepts-sampling) + [追蹤標頭](#xray-concepts-tracingheader) + [篩選條件表達式](#xray-concepts-filterexpressions) + [群組](#xray-concepts-groups) + [標註和中繼資料](#xray-concepts-annotations) + [錯誤、故障和例外狀況](#xray-concepts-errors) ## 客群 執行應用程式邏輯的運算資源會以**區段**形式傳送與其工作相關的資料。區段中提供資源的名稱、請求的詳細資訊，以及完成的工作詳細資訊。例如，當 HTTP 請求到達您的應用程式時，它可以記錄以下相關資料： + **主機** – 主機名稱、別名或 IP 地址 + **請求 – **方法、用戶端地址、路徑、使用者代理程式 + **回應** – 狀態、內容 + **完成的工作 – **開始和結束時間、子區段 + **發生的問題** – [錯誤、故障和例外狀況](#xray-concepts-errors)，包括自動擷取例外狀況堆疊。 ![\[X-Ray 追蹤的區段資料\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-cw-segment-overview.png) X-Ray SDK 會從請求和回應標頭、應用程式中的程式碼，以及其執行所在 AWS 資源的中繼資料中收集資訊。您可以透過修改應用程式組態或程式碼來檢測傳入請求、下游請求和 AWS SDK 用戶端，來選擇要收集的資料。 **轉送的請求** 如果負載平衡器或其他中介裝置轉送請求到您的應用程式，X-Ray 會從請求中的 `X-Forwarded-For`標頭取得用戶端 IP，而不是從 IP 封包中的來源 IP 取得用戶端 IP。為轉送請求記錄的用戶端 IP 可能是偽造的，因此不應受信任。 您可以使用 X-Ray 開發套件來記錄註釋[和中繼資料等其他資訊。](#xray-concepts-annotations)如需結構詳細資訊與區段和子區段中所記錄的資訊，請參閱[AWS X-Ray 區段文件](xray-api-segmentdocuments.md)。區段文件的大小上限為 64 kB。 ## 子區段 區段可以將完成工作的資料細分為**子區段**。子區段可提供更精確的計時資訊，以及應用程式為滿足原始請求所做的下游呼叫詳細資訊。子區段可以包含有關呼叫 AWS 服務、外部 HTTP API 或 SQL 資料庫的其他詳細資訊。您甚至可以定義任意子區段來檢測應用程式的特定函數或程式碼行。 ![\[子區段可提供更精確的資訊\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-cw-timeline-segment.png) 對於不傳送自己的區段的服務，例如 Amazon DynamoDB，X-Ray 會使用子區段在追蹤地圖上產生*推斷區段*和下游節點。這可讓您查看所有下游相依性，即使這些相依性不支援追蹤，或屬於外部相依性亦同。 子區段會以用戶端形式來代表您應用程式的下游呼叫檢視。如果下游服務也經過檢測，其傳送的區段則會取代從上游用戶端子區段產生的推斷區段。服務圖表的節點一律使用來自服務區段的資訊；兩個節點之間的邊緣則會使用上游服務的子區段。 例如，當您使用經檢測的 AWS SDK 用戶端呼叫 DynamoDB 時，X-Ray SDK 會記錄該呼叫的子區段。DynamoDB 不會傳送區段，因此追蹤中的推斷區段、服務圖表上的 DynamoDB 節點，以及服務和 DynamoDB 之間的邊緣都包含子區段中的資訊。 ![\[檢測應用程式與 DynamoDB 之間的邊緣。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-cw-servicemap-ddb-edge.png) 當您使用經檢測的應用程式呼叫其他經檢測的服務時，下游服務會傳送自己的區段以記錄上游服務在子區段中記錄的相同呼叫檢視。在服務圖表中，兩種服務的節點都會包含來自這些服務區段的計時和錯誤資訊，而之間的邊緣則包含來自上游服務子區段的資訊。 ![\[經檢測的應用程式呼叫其他經檢測的應用程式。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-cw-servicemap-instrumented-edge.png) 這兩種檢視都很實用，因為下游服務會精確記錄請求的工作開始和結束時間，而上游服務會記錄請求的往返延遲，包括請求在這兩項服務之間移動所花的時間。 ## 服務圖表 X-Ray 會使用應用程式傳送的資料來產生**服務圖表**。每個將資料傳送至 X-Ray AWS 的資源都會在圖形中顯示為服務。**邊緣**可連線至各種服務，這些服務則協力為請求提供服務。邊緣會將用戶端連線至您的應用程式，並將您的應用程式連線至其所用的下游服務和資源。 **服務名稱** 區段的 `name`應該符合產生區段之服務的網域名稱或邏輯名稱。不過，這不會強制執行。具有 許可的任何應用程式[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)都可以以任何名稱傳送客群。 服務圖表是一種 JSON 文件，其中包含構成您應用程式的服務和資源相關資訊。X-Ray 主控台使用服務圖表來產生視覺化*或服務映射*。 ![\[追蹤映射\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-cw-servicemap-simplified.png) 對於分散式應用程式，X-Ray 會將處理具有相同追蹤 ID 之請求的所有 服務節點合併為單一服務圖表。請求命中的第一個服務會新增[追蹤標頭](#xray-concepts-tracingheader)，而系統會在前端和其呼叫的服務之間傳播此標頭。 例如，[Scorekeep](xray-scorekeep.md) 會執行呼叫微服務的 Web API ( AWS Lambda 函數)，以使用 Node.js 程式庫來產生隨機名稱。適用於 Java 的 X-Ray 開發套件會產生追蹤 ID，並將其包含在對 Lambda 的呼叫中。Lambda 會傳送追蹤資料並將追蹤 ID 傳遞給函數。適用於 Node.js 的 X-Ray 開發套件也會使用追蹤 ID 來傳送資料。因此，API、Lambda 服務和 Lambda 函數的節點都會在追蹤映射上顯示為個別但已連線的節點。 服務圖表資料會保留 30 天。 ## 追蹤 **追蹤 ID** 可追蹤透過應用程式的請求路徑。追蹤會收集由單一請求所產生的所有區段。該請求通常是 HTTP GET 或 POST 請求，它會通過負載平衡器、命中您的應用程式碼，以及產生對其他服務 AWS 或外部 Web APIs下游呼叫。第一個與 HTTP 請求互動的支援服務會為請求新增追蹤 ID，並向下游傳播以追蹤延遲、處理和其他請求資料。 ![\[追蹤的時間軸檢視，其會收集由單一請求所產生的所有區段\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/xray-trace-details-cw.png) 如需 X-Ray 追蹤計費方式的資訊，請參閱[AWS X-Ray 定價](https://aws.amazon.com/xray/pricing/)。追蹤資料會保留 30 天。 ## 抽樣 為了確保有效率的追蹤，並提供應用程式提供的請求代表性範例，X-Ray SDK 會套用**取樣**演算法來判斷要追蹤哪些請求。根據預設，X-Ray 開發套件每秒記錄第一個請求，以及任何額外請求的 5%。 為了避免開始使用時產生的服務費用，預設的抽樣費率都很保守。您可以設定 X-Ray 來修改預設抽樣規則，並根據服務或請求的屬性設定套用抽樣的其他規則。 例如，您可能想要停用取樣，並追蹤所有修改狀態或處理使用者或交易的呼叫請求。若是大量唯讀呼叫 (例如背景輪詢、運作狀態檢查或連線維護)，您可以用低費率抽樣但仍獲得足夠的資料，以查看發生的任何問題。 如需詳細資訊，請參閱[設定 取樣規則](xray-console-sampling.md)。 ## 追蹤標頭 所有請求都會追蹤，並到可設定的最低限度為止。到達該最低限度之後，就會追蹤某個百分比的請求，以避免不必要的成本。取樣決策和追蹤 ID 會新增至名為 **的追蹤標頭**中的 HTTP 請求`X-Amzn-Trace-Id`。請求命中的第一個 X-Ray-integrated服務會新增追蹤標頭，由 X-Ray SDK 讀取並包含在回應中。 **Example 含根追蹤 ID 和抽樣決策的追蹤標頭** ``` X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1 ``` **追蹤標頭的安全性** 追蹤標頭可以源自 X-Ray 開發套件 AWS 服務、 或用戶端請求。您的應用程式可以從傳入的請求移除 `X-Amzn-Trace-Id`，以避免使用者將追蹤 ID 或抽樣決策新增到請求時發生問題。 如果請求是從經檢測的應用程式產生，則追蹤標頭也可以包含父區段 ID。例如，如果您的應用程式使用經檢測的 HTTP 用戶端呼叫下游 HTTP Web API，X-Ray SDK 會將原始請求的區段 ID 新增至下游請求的追蹤標頭。為下游請求提供服務的經檢測應用程式，可以記錄父區段 ID 以連線這兩個請求。 **Example 含根追蹤 ID、父區段 ID 和抽樣決策的追蹤標頭** ``` X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1 ``` `Lineage` 可能會由 Lambda 和其他 附加到追蹤標頭 AWS 服務 ，作為其處理機制的一部分，不應直接使用。 **Example 使用 Lineage 追蹤標頭** ``` X-Amzn-Trace-Id: Root=1-5759e988-bd862e3fe1be46a994272793;Parent=53995c3f42cd8ad8;Sampled=1;Lineage=25:a87bd80c:1 ``` ## 篩選條件表達式 即便使用抽樣，複雜的應用程式仍會產生大量資料。 AWS X-Ray 主控台提供easy-to-navigate的服務圖表檢視。它會顯示運作狀況和效能資訊，以協助您識別問題並找出最佳化應用程式的機會。若要進階追蹤，您可以向下切入以追蹤個別請求，或使用**篩選條件表達式**，以尋找與特定路徑或使用者相關的追蹤。 ![\[向下切入以追蹤個別請求\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-filter-httpurlCONTAINS-cw.png) ## 群組 X-Ray 擴充篩選條件表達式也支援 群組功能。使用篩選條件表達式，即可以定義條件，以接受追蹤到群組。 您可以依名稱或依 Amazon Resource Name (ARN) 呼叫 群組，以產生自己的服務圖表、追蹤摘要和 Amazon CloudWatch 指標。建立群組後，傳入的追蹤會在存放在 X-Ray 服務中時，針對群組的篩選條件表達式進行檢查。符合每個條件的追蹤數量指標每分鐘都會發佈至 CloudWatch。 更新群組的篩選條件表達式不會變更已記錄的資料。更新僅適用於後續追蹤。這會導致圖表合併新舊表達式。若要避免這種情況，請刪除目前群組並建立新的群組。 **注意** 群組的計費方式是根據符合篩選條件表達式的擷取追蹤。如需詳細資訊，請參閱 [AWS X-Ray 定價](https://aws.amazon.com/xray/pricing/)。 如需 群組的詳細資訊，請參閱 [設定 群組](xray-console-groups.md)。 ## 標註和中繼資料 當您檢測應用程式時，X-Ray 開發套件會記錄傳入和傳出請求、使用 AWS 的資源和應用程式本身的相關資訊。您可以藉由註釋和中繼資料形式，將其他資訊新增至區段文件。註釋和中繼資料會在追蹤層級彙總，並且可以新增至任何區段或子區段。 **註釋**是簡單的鍵/值對，其會建立索引以與[篩選條件表達式](xray-console-filters.md)搭配使用。使用標記記錄您想要用來在主控台將追蹤分組的資料，或是在呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 時使用標記。 X-Ray 為每個追蹤編製最多 50 個註釋的索引。 **中繼資料**為含有任何類型值的鍵/值對，包括物件和清單，但不會建立索引。您可以使用中繼資料，來記錄想要存放於追蹤但不需用於搜尋追蹤的資料。 您可以在 CloudWatch 主控台的[追蹤詳細資訊](xray-console-traces.md#xray-console-traces-view)頁面中，檢視區段或子區段詳細資訊視窗中的註釋和中繼資料。 ![\[您可以在 CloudWatch 主控台的區段或子區段詳細資訊中檢視註釋和中繼資料\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-cw-subsegment-metadata.png) ## 錯誤、故障和例外狀況 X-Ray 會追蹤應用程式程式碼中發生的錯誤，以及下游服務傳回的錯誤。錯誤分類如下。 + **`Error`** – 用戶端錯誤 (400 系列錯誤） + **`Fault`** – 伺服器故障 (500 系列錯誤） + **`Throttle`** – 調節錯誤 (429 個請求過多） 當您的應用程式提供經檢測的請求時發生例外狀況時，X-Ray 開發套件會記錄例外狀況的詳細資訊，包括可用的堆疊追蹤。您可以在 X-Ray 主控台中的[客群詳細資訊](xray-console-traces.md#xray-console-segments)下檢視例外狀況。