本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 選擇界面
AWS X-Ray 可讓您深入了解應用程式的運作方式，以及與其他 服務和資源的互動方式。在您檢測或設定應用程式之後，X-Ray 會在應用程式提供請求時收集追蹤資料。您可以分析此追蹤資料，以識別效能問題、故障診斷錯誤，以及最佳化您的 資源。本指南說明如何使用下列準則與 X-Ray 互動：
+ AWS 管理主控台 如果您想要快速開始使用，請使用 ，或者可以使用預先建置的視覺化來執行基本任務。
+ 選擇 Amazon CloudWatch 主控台以取得包含所有 X-Ray 主控台功能的最新使用者體驗。
+ 如果您想要更簡單的界面或不想變更與 X-Ray 互動的方式，請使用 X-Ray 主控台。
+ 如果您需要比 更多的自訂追蹤、監控或記錄功能，請使用 開發套件 AWS 管理主控台 。
+ ADOT 如果您想要以開放原始碼 SDK 為基礎，並新增 AWS 安全性和最佳化層的廠商無關 OpenTelemetry SDK，請選擇 SDK。
+ 如果您想要更簡單的 SDK 或不想要更新您的應用程式碼，請選擇 X-Ray 開發套件。
+ 如果 SDK 不支援應用程式的程式設計語言，請使用 X-Ray API 操作。
下圖可協助您選擇如何與 X-Ray 互動：
![\[X-Ray 會顯示應用程式請求的詳細資訊。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/xray-choose-interface.png)
**Topics**
+ [使用 SDK](aws-xray-interface-sdk.md)
+ [使用主控台](aws-xray-interface-console.md)
+ [使用 X-Ray API](xray-api.md)
# 使用 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 管理主控台。您也可以使用 AWS SDK 來開發使用 X-Ray APIs程式。您可以使用 AWS Distro for OpenTelemetry (ADOT) 開發套件或 X-Ray 開發套件。
如果您使用 SDK，您可以在檢測應用程式和設定收集器或代理程式時，將自訂新增至工作流程。您可以使用 SDK 來執行無法使用 執行的下列任務 AWS 管理主控台：
+ 發佈自訂指標 – 高解析度低至 1 秒的範例指標，使用多個維度來新增指標的相關資訊，並將資料點彙總至統計資料集。
+ 自訂您的收集器 – 自訂收集器任何部分的組態，包括接收者、處理器、匯出器和連接器。
+ 自訂您的檢測 – 自訂區段和子區段、新增自訂鍵值對做為屬性，以及建立自訂指標。
+ 以程式設計方式建立和更新抽樣規則。
如果您想要彈性地使用標準 ADOT SDK 並新增多層 AWS 安全性和最佳化，請使用 OpenTelemetry SDK。 AWS Distro for OpenTelemetry (ADOT) SDK 是與廠商無關的套件，允許與其他廠商和非AWS 服務的後端整合，而無需重新檢測您的程式碼。
如果您已經在使用 X-Ray 開發套件、僅與 AWS 後端整合，而且不想變更您與 X-Ray 或應用程式程式碼互動的方式，請使用 X-Ray 開發套件。
如需每個功能的詳細資訊，請參閱 [選擇 AWS Distro for OpenTelemetry 和 X-Ray SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing)。
## 使用 ADOT SDK
SDK ADOT是一組開放原始碼 APIs、程式庫和代理程式，可將資料傳送至後端服務。 ADOT 受 支援 AWS、與多個後端和代理程式整合，並提供OpenTelemetry社群維護的大量開放原始碼程式庫。使用 ADOT 開發套件來檢測您的應用程式，並收集日誌、中繼資料、指標和追蹤。您也可以使用 ADOT 來監控服務，並根據 CloudWatch 中的指標設定警示。
如果您使用 ADOT開發套件，您可以搭配 代理程式使用下列選項：
+ 搭配 [CloudWatch 代理程式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)使用 ADOT SDK – 建議使用。
+ 搭配 [ADOT Collector](https://aws-otel.github.io/docs/getting-started/collector) 使用 ADOT 開發套件 – 如果您想要搭配 AWS 多層安全性和最佳化使用與廠商無關的軟體，建議使用 。
若要使用 ADOT SDK，請執行下列動作：
+ 使用 ADOT SDK 檢測您的應用程式。如需詳細資訊，請參閱 [ADOT 技術文件中程式設計語言的文件](https://aws-otel.github.io/docs/introduction)。
+ 設定ADOT收集器以告知收集資料的位置。
ADOT 收集器收到您的資料後，會將其傳送至您在ADOT組態中指定的後端。 ADOT可以將資料傳送至多個後端，包括 以外的廠商 AWS，如下圖所示：
![\[您可以在檢測應用程式和設定收集器時自訂 ADOT 收集器。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/adot-sdk.png)
AWS 會定期更新ADOT以新增功能，並與 [OpenTelemetry](https://opentelemetry.io/docs/) 架構保持一致。開發的更新和未來計劃ADOT是可供公眾使用的[藍圖](https://github.com/orgs/aws-observability/projects/4)的一部分。 ADOT支援多種程式設計語言，包括下列項目：
+ Go
+ Java
+ JavaScript
+ Python
+ .NET
+ Ruby
+ PHP
如果您使用的是 Python， ADOT 可以自動檢測您的應用程式。若要開始使用 ADOT，請參閱 Distro for OpenTelemetry Collector [簡介](https://aws-otel.github.io/docs/introduction)和入門。 [AWS OpenTelemetry ](https://aws-otel.github.io/docs/getting-started/collector)
## 使用 X-Ray SDK
X-Ray SDK 是一組 AWS APIs和程式庫，可將資料傳送至 AWS 後端服務。使用 X-Ray 開發套件來檢測您的應用程式並收集追蹤資料。您無法使用 X-Ray 開發套件來收集日誌或指標資料。
如果您使用 X-Ray 開發套件，您可以搭配 代理程式使用下列選項：
+ 搭配 使用 X-Ray 開發套件 [AWS X-Ray 協助程式](xray-daemon.md) – 如果您不想更新應用程式碼，請使用此選項。
+ 搭配 CloudWatch 代理程式使用 X-Ray 開發套件 – （建議） CloudWatch 代理程式與 X-Ray 開發套件相容。
若要使用 X-Ray 開發套件，請執行下列動作：
+ 使用 X-Ray SDK 檢測您的應用程式。
+ 設定收集器以告知收集資料的位置。您可以使用 CloudWatch 代理程式或 X-Ray 協助程式來收集追蹤資訊。
收集器或代理程式收到您的資料後，會將其傳送至您在代理程式組態中指定的 AWS 後端。X-Ray SDK 只能將資料傳送至 AWS 後端，如下圖所示：
![\[搭配 CloudWatch 代理程式或 X-Ray 協助程式使用 X-Ray 開發套件。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/xray-sdk.png)
如果您使用的是 Java，您可以使用 X-Ray 開發套件自動檢測您的應用程式。若要開始使用 X-Ray 開發套件，請參閱與下列程式設計語言相關聯的程式庫：
+ [Go](xray-go.md)
+ [Java](xray-java.md)
+ [Node.js](xray-nodejs.md)
+ [Python](xray-python.md)
+ [.NET](xray-dotnet.md)
+ [Ruby](xray-ruby.md)
# 使用主控台
如果您想要需要最低編碼的圖形使用者介面 (GUI)，請使用 主控台。初次使用 X-Ray 的使用者可以使用預先建置的視覺化效果快速入門，並執行基本任務。您可以直接從主控台執行下列動作：
+ 啟用 X-Ray。
+ 檢視應用程式效能的高階摘要。
+ 檢查應用程式的運作狀態。
+ 識別高階錯誤。
+ 檢視基本追蹤摘要。
您可以使用位於 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)：// 的 Amazon CloudWatch 主控台或位於 [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)：// 的 X-Ray 主控台與 X-Ray 互動。
## 使用 Amazon CloudWatch 主控台
CloudWatch 主控台包含從 X-Ray 主控台重新設計的新 X-Ray 功能，讓您更輕鬆地使用。如果您使用 CloudWatch 主控台，您可以檢視 CloudWatch 日誌和指標以及 X-Ray 追蹤資料。使用 CloudWatch 主控台來檢視和分析資料，包括下列項目：
+ X-Ray 追蹤 – 檢視、分析和篩選與您的應用程式相關聯的追蹤，因為它可處理請求。使用這些追蹤來尋找高延遲、偵錯錯誤，並最佳化您的應用程式工作流程。檢視追蹤地圖和服務地圖，以查看應用程式工作流程的視覺化呈現。
+ 日誌 – 檢視、分析和篩選應用程式產生的日誌。使用日誌對錯誤進行故障診斷，並根據特定日誌值設定監控。
+ 指標 – 使用資源發出的指標或建立自己的指標，測量和監控您的應用程式效能。在圖形和圖表中檢視這些指標。
+ 監控網路和基礎設施 – 監控主要網路是否有中斷，以及基礎設施的運作狀態和效能，包括容器化應用程式、 AWS 其他服務和用戶端。
+ 下列**使用 X-Ray 主控台區段中列出的 X-Ray 主控台**的所有功能。
如需 CloudWatch 主控台的詳細資訊，請參閱 [Amazon CloudWatch 入門](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/GettingStarted.html)。
登入 Amazon CloudWatch 主控台，網址為 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。
## 使用 X-Ray 主控台
X-Ray 主控台提供應用程式請求的分散式追蹤。如果您想要更簡單的主控台體驗或不想更新您的應用程式碼，請使用 X-Ray 主控台。 AWS 不再開發 X-Ray 主控台。X-Ray 主控台包含受檢測應用程式的下列功能：
+ [洞見](xray-console-insights.md) – 自動偵測應用程式效能中的異常，並找出根本原因。Insights 包含在 CloudWatch 主控台的 **Insights** 下。如需詳細資訊，請參閱《》中的**使用 X-Ray Insights**[使用 X-Ray 主控台](#xray-console)。
+ 服務映射 – 檢視應用程式及其與用戶端、資源、服務和相依性的連線的圖形結構。
+ 追蹤 – 查看應用程式在處理請求時所產生的追蹤概觀。使用追蹤資料來了解您的應用程式如何根據基本指標執行，包括HTTP回應和回應時間。
+ 分析 – 使用回應時間分佈圖表來解譯、探索和分析追蹤資料。
+ 組態 – 建立自訂追蹤以變更下列項目的預設組態：
+ 取樣 – 建立規則，定義取樣應用程式以取得追蹤資訊的頻率。如需詳細資訊，請參閱在 [使用 X-Ray 主控台](#xray-console) 中**設定抽樣規則**。
+ [加密](xray-console-encryption.md) – 使用您可以使用 稽核或停用的金鑰來加密靜態資料 AWS Key Management Service。
+ 群組 – 使用篩選條件表達式來定義具有常見功能的追蹤群組，例如 URL 名稱或回應時間。如需詳細資訊，請參閱[設定群組](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-groups)。
登入位於 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) 的 X-Ray 主控台。
## 探索 X-Ray 主控台
使用 X-Ray 主控台檢視應用程式提供之請求的服務映射和相關追蹤，以及設定群組和取樣規則，這些規則會影響追蹤傳送至 X-Ray 的方式。
**注意**
X-Ray Service 映射和 CloudWatch ServiceLens 映射已合併到 Amazon CloudWatch 主控台中的 X-Ray 追蹤映射中。開啟 [CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)，然後從左側導覽窗格選擇 **X-Ray 追蹤下的追蹤****映射**。
CloudWatch 現在包含 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)，可探索和監控您的應用程式服務、用戶端、Synthetics Canary 和服務相依性。使用 Application Signals 查看服務清單或視覺化地圖，根據您的服務等級目標 (SLO) 檢視運作狀態指標，並深入了解相關的 X-Ray 追蹤以取得更詳細的疑難排解。
主要 X-Ray 主控台頁面是追蹤映射，這是 X-Ray 從應用程式產生的追蹤資料產生的 JSON 服務圖形視覺呈現。映射由您帳戶中每個處理請求的應用程式服務節點、代表請求來源的上游用戶端節點，以及代表處理請求過程中應用程式所使用 web 服務及資源的下游服務節點組成。還有其他頁面可檢視追蹤和追蹤詳細資訊，以及設定群組和取樣規則。
檢視 X-Ray 的主控台體驗，並與下列各節中的 CloudWatch 主控台進行比較。
**Topics**
+ [使用 Amazon CloudWatch 主控台](#aws-xray-interface-console-cw)
+ [使用 X-Ray 主控台](#xray-console)
+ [探索 X-Ray 主控台](#xray-console-explore)
+ [使用 X-Ray 追蹤映射](xray-console-servicemap.md)
+ [檢視追蹤和追蹤詳細資訊](xray-console-traces.md)
+ [使用篩選條件表達式](xray-console-filters.md)
+ [跨帳戶追蹤](xray-console-crossaccount.md)
+ [追蹤事件驅動型應用程式](xray-tracelinking.md)
+ [使用延遲長條圖](xray-console-histograms.md)
+ [使用 X-Ray 洞察](xray-console-insights.md)
+ [與 Analytics 主控台互動](xray-console-analytics.md)
+ [設定 群組](xray-console-groups.md)
+ [設定 取樣規則](xray-console-sampling.md)
+ [設定自適應抽樣](xray-adaptive-sampling.md)
+ [主控台深層連結](xray-console-deeplinks.md)
# 使用 X-Ray 追蹤映射
檢視 X-Ray 追蹤映射，以識別發生錯誤的服務、具有高延遲的連線，或失敗請求的追蹤。
**注意**
CloudWatch 現在包含 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)，可探索和監控您的應用程式服務、用戶端、合成 Canary 和服務相依性。使用 Application Signals 查看服務清單或視覺化地圖，根據您的服務等級目標 (SLO) 檢視運作狀態指標，並深入了解相關的 X-Ray 追蹤以取得更詳細的疑難排解。
X-Ray 服務映射和 CloudWatch ServiceLens 映射會合併到 Amazon CloudWatch 主控台內的 X-Ray 追蹤映射中。開啟 [CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)，然後從左側導覽窗格選擇 **X-Ray 追蹤下的追蹤****地圖**。
## 檢視追蹤映射
追蹤映射是應用程式所產生追蹤資料的視覺化呈現。地圖會顯示服務節點，其可處理請求、代表請求來源的上游用戶端節點，以及代表應用程式在處理請求時所使用的 Web 服務和資源的下游服務節點。
追蹤映射會顯示使用 Amazon SQS 和 Lambda 之事件驅動應用程式的追蹤連線檢視。如需詳細資訊，請參閱[追蹤事件驅動的應用程式](xray-tracelinking.md)。追蹤映射也支援[跨帳戶追蹤](xray-console-crossaccount.md)，在單一映射中顯示來自多個帳戶的節點。
------
#### [ CloudWatch console ]
**在 CloudWatch 主控台中檢視追蹤映射**
1. 開啟 [CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)。在左側導覽窗格中的 **X-Ray 追蹤區段下，選擇****追蹤地圖**。
![\[CloudWatch 主控台追蹤映射頁面\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-servicemap-cw.png)
1. 選擇服務節點來檢視該節點的請求，或是兩個節點間的邊緣來檢視在該連線上進行的請求。
1. 其他資訊會顯示在追蹤映射下方，包括指標、提醒和回應時間分佈的標籤。在**指標**索引標籤上，選取每個圖形內的範圍來向下切入以檢視更多詳細資訊，或選擇**錯誤**或**錯誤**選項來篩選追蹤。在**回應時間分佈**索引標籤上，選取圖形內的範圍，以依回應時間篩選追蹤。
![\[Dashboard showing latency, requests, and faults metrics for an ElasticBeanstalk environment.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-cw-servicemap-node-detail.png)
1. 選擇檢視追蹤來**檢視追蹤**，或者如果已套用篩選條件，請選擇**檢視篩選的追蹤**。
1. 選擇**檢視日誌**以查看與所選節點相關聯的 CloudWatch 日誌。並非所有追蹤映射節點都支援檢視日誌。如需詳細資訊，請參閱對 [ CloudWatch 日誌進行故障](xray-troubleshooting.md#xray-troubleshooting-Nologs)診斷。
追蹤映射會以顏色概述每個節點內的問題：
+ **紅色**表示伺服器故障 (500 系列錯誤)
+ **黃色**表示用戶端錯誤 (400 系列錯誤)
+ **紫色**表示調節錯誤 (429 請求數太多)
如果您的追蹤映射很大，請使用螢幕控制項或滑鼠來放大和縮小和移動映射。
------
#### [ X-Ray console ]
**檢視服務映射**
1. 開啟 [X-Ray 主控台](https://console.aws.amazon.com/xray/home#)。預設會顯示服務映射。您也可以從左側導覽窗格中選擇**服務地圖**。
![\[X-Ray 主控台服務映射頁面\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-servicemap-xray.png)
1. 選擇服務節點來檢視該節點的請求，或是兩個節點間的邊緣來檢視在該連線上進行的請求。
1. 使用回應分佈[長條圖](xray-console-histograms.md)依持續時間篩選追蹤，然後選取您要檢視追蹤的狀態碼。然後選擇 **View traces (檢視追蹤)** 來使用套用的篩選條件表達式開啟追蹤清單。
![\[Response distribution graph showing latency peaks and service details for Scorekeep AWS ECS container.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-servicemap-nodedetail-xray.png)
服務映射會透過根據成功呼叫與錯誤及故障的比例，將每個節點標上顏色，來指出每個節點的運作狀態。
+ **綠色**表示成功呼叫
+ **紅色**表示伺服器故障 (500 系列錯誤)
+ **黃色**表示用戶端錯誤 (400 系列錯誤)
+ **紫色**表示調節錯誤 (429 請求數太多)
如果您的服務映射很大，請使用螢幕控制項或滑鼠來放大和縮小和移動映射。
------
**注意**
X-Ray 追蹤映射最多可顯示 10，000 個節點。在服務節點總數超過此限制的罕見情況下，您可能會收到錯誤，無法在主控台中顯示完整的追蹤映射。
## 依群組篩選追蹤映射
使用[篩選條件表達](xray-console-filters.md)式，您可以定義要在群組中包含追蹤的條件。使用下列步驟在追蹤映射中顯示該特定群組。
------
#### [ CloudWatch console ]
從追蹤映射左上角的群組篩選條件中選擇群組名稱。
![\[Search bar for filtering by X-Ray group, with "TestGroup" displayed as an option.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-servicemap-groups-cw.png)
------
#### [ X-Ray console ]
從下拉式功能表左側的搜尋列，選擇群組名稱。
![\[Drop-down menu showing Default, TestGroup, Create group, and Learn more options.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-select-console.png)
------
現在將篩選服務映射，以顯示符合所選群組篩選條件表達式的追蹤。
## 追蹤地圖圖例和選項
追蹤映射包含圖例和數個選項，用於自訂映射顯示。
------
#### [ CloudWatch console ]
選擇地圖右上角的**圖例和選項**下拉式清單。選擇節點中顯示的內容，包括：
+ **指標**會顯示平均回應時間和在所選時間範圍內每分鐘傳送的追蹤數量。
+ **節點**會顯示每個節點內的服務圖示。
從**偏好設定**窗格選擇其他地圖設定，可透過地圖右上角的齒輪圖示存取。這些設定包括選取用於判斷每個節點大小的指標，以及哪些 Canary 應顯示在地圖上。
------
#### [ X-Ray console ]
選擇地圖右上角的**地圖圖例**連結，以顯示服務地圖圖例。您可以在追蹤映射的右下角選擇服務映射選項，包括：
+ **服務圖示**會切換每個節點內顯示的內容，顯示服務圖示，或在所選時間範圍內每分鐘傳送的平均回應時間和追蹤數量。
+ **節點大小：無**會將所有節點設為相同大小。
+ **節點大小調整：運作**狀態會依受影響的請求數量來調整節點大小，包括錯誤、故障或限流請求。
+ **節點大小：流量**會依請求總數來調整節點大小。
------
# 檢視追蹤和追蹤詳細資訊
使用 X-Ray 主控台中的**追蹤**頁面，依 URL、回應碼或追蹤摘要中的其他資料尋找追蹤。從追蹤清單中選取追蹤之後，**追蹤詳細資訊**頁面會顯示與所選追蹤相關聯的服務節點映射，以及追蹤區段的時間軸。
## 檢視追蹤
------
#### [ CloudWatch console ]
**在 CloudWatch 主控台中檢視追蹤**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在左側導覽窗格中，選擇 **X-Ray 追蹤**，然後選擇**追蹤**。您可以依群組篩選或輸入[篩選條件表達](xray-console-filters.md)式。這會篩選頁面底部的追蹤區段中顯示的**追蹤**。
或者，您可以使用服務映射導覽至特定服務節點，然後檢視追蹤。這會開啟已套用查詢**的追蹤**頁面。
1. 在查詢**精簡器區段中精簡您的查詢**。若要依常見屬性篩選追蹤，請從**精簡查詢依據**旁的向下箭頭選擇一個選項。選項包括下列項目：
+ 節點 – 依服務節點篩選追蹤。
+ 資源 ARN – 依與追蹤相關聯的資源篩選追蹤。這些資源的範例包括 Amazon Elastic Compute Cloud (Amazon EC2) 執行個體、 AWS Lambda 函數或 Amazon DynamoDB 資料表。
+ 使用者 – 使用使用者 ID 篩選追蹤。
+ 錯誤根本原因訊息 – 依錯誤根本原因篩選追蹤。
+ URL – 依應用程式使用的 URL 路徑篩選追蹤。
+ HTTP 狀態碼 – 依應用程式傳回的 HTTP 狀態碼篩選追蹤。您可以指定自訂回應代碼，或從下列項目中選取：
+ `200` – 請求成功。
+ `401` – 請求缺少有效的身分驗證登入資料。
+ `403` – 請求缺少有效許可。
+ `404` – 伺服器找不到請求的資源。
+ `500` – 伺服器遇到未預期的條件並產生內部錯誤。
選擇一或多個項目，然後選擇**新增至查詢**，以新增至頁面頂端的篩選條件表達式。
1. 若要尋找單一追蹤，請直接在查詢欄位中輸入[追蹤 ID](xray-api-sendingdata.md#xray-api-traceids)。您可以使用 X-Ray 格式或全球資訊網協會 (W3C) 格式。例如，使用 [AWS Distro for OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel) 建立的追蹤是 W3C 格式。
**注意**
當您查詢使用 W3C-format追蹤 ID 建立的追蹤時，主控台會以 X-Ray 格式顯示相符的追蹤。例如，如果您`4efaaf4d1e8720b39541901950019ee5`以 W3C 格式查詢 ，主控台會顯示 X-Ray 對等項目：`1-4efaaf4d-1e8720b39541901950019ee5`。
1. 選擇隨時**執行查詢**，以在頁面底部的追蹤區段中顯示相符**的追蹤**清單。
1. 若要顯示單一追蹤的追蹤**詳細資訊**頁面，請從清單中選擇追蹤 ID。
下圖顯示**追蹤映射**，其中包含與追蹤相關聯的服務節點，以及節點之間的邊緣，代表由構成追蹤的區段所採取的路徑。**追蹤摘要**遵循**追蹤地圖**。摘要包含範例`GET`操作、其**回應碼**、追蹤執行所花費的**持續時間**，以及請求的**存留期**的相關資訊。**客群時間軸**遵循**追蹤摘要**，顯示追蹤客群和子客群的持續時間。
![\[追蹤映射、摘要和客群時間軸會詳細說明追蹤中服務節點和客群的相關資訊。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/xray-trace-details-cw.png)
如果您有使用 Amazon SQS 和 Lambda 的事件驅動應用程式，您可以在追蹤**映射中查看每個請求的追蹤**連線檢視。在地圖中，來自訊息生產者的追蹤會連結到來自 AWS Lambda 消費者的追蹤，並以虛線邊緣顯示。如需事件驅動型應用程式的詳細資訊，請參閱 [追蹤事件驅動型應用程式](xray-tracelinking.md)。
**追蹤**和**追蹤詳細資訊**頁面也支援[跨帳戶追蹤](xray-console-crossaccount.md)，可在追蹤清單中和單一追蹤映射內列出來自多個帳戶的追蹤。
------
#### [ X-Ray console ]
**在 X-Ray 主控台中檢視追蹤**
1. 在 X-Ray 主控台中開啟[追蹤](https://console.aws.amazon.com/xray/home#/traces)頁面。**追蹤概觀**面板會顯示依常見功能分組的追蹤清單，包括**錯誤根本原因**、**ResourceARN** 和 **InstanceId**。
1. 若要選取常見功能以檢視一組分組的追蹤，請展開**分組依據**旁的向下箭頭。下圖顯示依 URL 分組的追蹤概觀[AWS X-Ray 範例應用程式](xray-scorekeep.md)，以及相關聯的追蹤清單。
![\[依 URL 分組的範例追蹤概觀，後面接著追蹤清單，其中包含 ID、方法和回應等詳細資訊。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-traces.png)
1. 選擇追蹤的 **ID**，以在**追蹤清單**下檢視。您也可以在導覽窗格中選擇**服務映射**，以檢視特定服務節點的追蹤。然後，您可以檢視與該節點相關聯的追蹤。
**時間軸**索引標籤會顯示追蹤的請求流程，並包含下列項目：
+ 追蹤中每個區段的路徑映射。
+ 區段到達追蹤映射中節點所需的時間。
+ 對追蹤映射中的節點提出了多少請求。
下圖顯示與對範例應用程式提出之`GET`請求相關聯的**追蹤地圖**範例。箭頭顯示每個區段完成請求所採取的路徑。服務節點會顯示請求期間提出的`GET`請求數量。
![\[追蹤映射後面接著時間軸，其中包含區段、其持續時間、原始伺服器，以及相對於彼此的結尾。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/xray-trace-details.png)
如需**時間軸**索引標籤的詳細資訊，請參閱下列**探索追蹤時間軸**區段。
**原始資料**索引標籤會以 `JSON` 格式顯示追蹤的相關資訊，以及構成追蹤的區段和子區段。此資訊可能包括下列項目：
+ 時間戳記
+ 唯一 ID
+ 與區段或子區段相關聯的資源
+ 區段或子區段的來源或原始伺服器
+ 有關對應用程式請求的其他資訊，例如來自 HTTP 請求的回應
------
## 探索追蹤時間軸
**時間軸**區段會在水平長條旁顯示區段和子區段的階層，對應於他們用來完成任務的時間。清單中的第一個項目是區段，代表服務為單一請求記錄的所有資料。子區段會縮排，並列在區段後面。資料欄包含每個區段的相關資訊。
------
#### [ CloudWatch console ]
在 CloudWatch 主控台中，**客群時間軸**會提供下列資訊：
+ 第一欄：列出所選追蹤中的區段和子區段。
+ **區段狀態**欄：列出每個區段和子區段的狀態結果。
+ **回應碼**欄：列出區段或子區段提出的瀏覽器請求的 HTTP 回應狀態碼，當可用時。
+ **持續時間**欄：列出區段或子區段執行的時間長度。
+ **託管於**資料欄：列出執行區段或子區段的命名空間或環境，如適用。如需詳細資訊，請參閱[收集的維度和維度組合](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AppSignals-StandardMetrics.html#AppSignals-StandardMetrics-Dimensions)。
+ 最後一欄：顯示與時間軸中其他區段或子區段相關的區段或子區段執行持續時間對應的水平長條。
若要依服務節點分組區段和子區段清單，請開啟**依節點分組**。
------
#### [ X-Ray console ]
在追蹤詳細資訊頁面中，選擇**時間軸**索引標籤，以查看構成追蹤的每個區段和子區段的時間軸。
在 X-Ray 主控台中，**時間軸**會提供下列資訊：
+ **名稱**欄：列出追蹤中區段和子區段的名稱。
+ Res**.** 欄：列出區段或子區段提出的瀏覽器請求的 HTTP 回應狀態碼，當可用時。
+ **持續時間**欄：列出區段或子區段執行的時間長度。
+ **狀態**欄：列出區段或子區段狀態的結果。
+ 最後一欄：顯示與時間軸中其他區段或子區段相關的區段或子區段執行持續時間對應的水平長條。
若要查看主控台用來產生時間軸的原始追蹤資料，請選擇**原始資料**索引標籤。原始資料會顯示追蹤的相關資訊，以及以 `JSON` 格式編寫追蹤的區段和子區段。此資訊可能包括下列項目：
+ 時間戳記
+ 唯一 ID
+ 與區段或子區段相關聯的資源
+ 區段或子區段的來源或原始伺服器
+ 有關對應用程式提出請求的其他資訊，例如來自 HTTP 請求的回應。
------
當您使用經檢測的 AWS 開發套件HTTP、 或 SQL用戶端呼叫外部資源時，X-Ray 開發套件會自動記錄子區段。您也可以使用 X-Ray SDK 記錄任何函數或程式碼區塊的自訂子區段。自訂子區段開啟時記錄的其他子區段會成為自訂子區段的子區段。
## 檢視區段詳細資訊
從追蹤**時間軸**中，選擇要檢視其詳細資訊的客群名稱。
**區段詳細資訊**面板會顯示**概觀**、**資源**、**註釋**、**中繼資料**、**例外**狀況和 **SQL** 索引標籤。適用下列情況：
+ **Overview (概觀)** 標籤會顯示請求及回應的相關資訊。資訊包括名稱、開始時間、結束時間、持續時間、請求 URL、請求操作、請求回應碼，以及任何錯誤和故障。
+ 區段**的資源**索引標籤會顯示 X-Ray 開發套件的資訊，以及執行您應用程式 AWS 的資源。使用 X-Ray SDK 的 Amazon EC2 AWS Elastic Beanstalk或 Amazon ECS 外掛程式來記錄服務特定的資源資訊。如需外掛程式的詳細資訊，請參閱《》中的**服務外掛程式**一節[設定適用於 Java 的 X-Ray 開發套件](xray-sdk-java-configuration.md)。
+ 其餘索引標籤會顯示針對區段記錄的**註釋**、**中繼資料**和**例外**狀況。從檢測的請求產生例外狀況時，系統會自動擷取例外狀況。註釋和中繼資料包含您使用 X-Ray SDK 提供的操作記錄的其他資訊。若要將註釋或中繼資料新增至您的客群，請使用 X-Ray 開發套件。如需詳細資訊，請參閱 中使用 AWS X-Ray SDKs 檢測應用程式下列出的特定語言連結[檢測您的應用程式 AWS X-Ray](xray-instrumenting-your-app.md)。
## 檢視子區段詳細資訊
從追蹤時間軸中，選擇子區段的名稱以檢視其詳細資訊：
+ **概觀**索引標籤包含請求和回應的相關資訊。這包括名稱、開始時間、結束時間、持續時間、請求 URL、請求操作、請求回應碼，以及任何錯誤和故障。針對使用受檢測用戶端產生的子區段，**Overview (概觀)** 標籤包含從您應用程式觀點的請求和回應相關資訊。
+ 子區段**的資源**索引標籤會顯示用來執行子區段之 AWS 資源的詳細資訊。例如，資源索引標籤可能包含 AWS Lambda 函數 ARN、DynamoDB 資料表的相關資訊、呼叫的任何操作，以及請求 ID。
+ 其餘索引標籤會顯示子區段上記錄的**註釋**、**中繼資料**和**例外**狀況。從檢測的請求產生例外狀況時，系統會自動擷取例外狀況。註釋和中繼資料包含您使用 X-Ray SDK 提供的操作記錄的其他資訊。使用 X-Ray SDK 將註釋或中繼資料新增至您的客群。如需詳細資訊，請參閱 中使用 ** SDKs 檢測應用程式 AWS X-Ray **下列出的特定語言連結[檢測您的應用程式 AWS X-Ray](xray-instrumenting-your-app.md)。
針對自訂子區段，**Overview (概觀)** 標籤會顯示子區段的名稱，您可以設定該名稱來指定其記錄的程式碼或函數區域。如需詳細資訊，請參閱 中使用 ** AWS X-Ray SDKs 檢測應用程式**下列出的特定語言連結[使用適用於 Java 的 X-Ray 開發套件產生自訂子區段](xray-sdk-java-subsegments.md)。
下圖顯示自訂子區段的**概觀**索引標籤。概觀包含子區段 ID、父系 ID、名稱、開始和結束時間、持續時間、狀態和錯誤或故障。
![\[子區段的概觀資訊，包括 ID、父系 ID、名稱、時間、錯誤和故障。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-PUTrules-customsubsegment-overview.png)
自訂子區段的**中繼資料**索引標籤包含該子區段所用資源的JSON格式資訊。
# 使用篩選條件表達式
使用*篩選條件表達式*來檢視特定請求、服務、兩個服務之間的連線 （邊緣） 或滿足條件之請求的追蹤映射或追蹤。X-Ray 提供篩選條件表達式語言，可根據請求標頭中的資料、回應狀態和原始區段上的索引欄位來篩選請求、服務和邊緣。
當您選擇要在 X-Ray 主控台中檢視的追蹤期間時，可能會得到比主控台可顯示更多的結果。主控台會在右上角顯示已掃描的追蹤數目，但實際上可用的追蹤可能更多。您可以使用篩選條件表達式，將結果縮小為僅您要尋找的追蹤。
**Topics**
+ [篩選條件表達式詳細資訊](#xray-console-filters-details)
+ [搭配使用篩選條件表達式與群組](#groups)
+ [篩選條件表達式語法](#console-filters-syntax)
+ [布林值關鍵字](#console-filters-boolean)
+ [數字關鍵字](#console-filters-number)
+ [字串關鍵字](#console-filters-string)
+ [複雜關鍵字](#console-filters-complex)
+ [id 函數](#console-filters-functions)
## 篩選條件表達式詳細資訊
當您[在追蹤映射中選擇節點](xray-console-servicemap.md)時，主控台會根據節點的服務名稱，以及根據您的選擇存在的錯誤類型，建構篩選條件表達式。若要尋找顯示效能問題或與特定請求相關的追蹤，您可以調整主控台提供的表達式，或是自行建立。如果您使用 X-Ray SDK 新增註釋，您也可以根據註釋索引鍵的存在或索引鍵的值進行篩選。
**注意**
如果您在追蹤映射中選擇相對時間範圍並選擇節點，主控台會將時間範圍轉換為絕對開始和結束時間。為了確保搜尋結果顯示節點的追蹤，並避免掃描未作用中節點的時間，時間範圍只包含節點傳送追蹤的時間。若要搜尋相對於目前的時間，您可以在追蹤頁面切換回相對時間範圍，並再次掃描。
如果可用結果超過主控台可以顯示的範圍，主控台會顯示相符的追蹤數和已掃描的追蹤數。顯示的百分比為所選時間範圍內已掃描的百分比。若要確保結果中可以顯示所有相符的追蹤，請進一步縮小篩選條件表達式，或選擇較短的時間範圍。
若要先取得最新的結果，主控台會從時間範圍結尾開始掃描，並倒退進行。如果有大量追蹤，但僅有少數結果，主控台會將時間範圍分成區塊並平行掃描。進度列會顯示已掃描的部分時間範圍。
![\[Progress bar showing 52% of time range scanned, with 49 matching traces found.\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-tracescan-parallel.png)
## 搭配使用篩選條件表達式與群組
群組是由篩選條件表達式定義的追蹤集合。您可以使用 群組來產生額外的服務圖表，並提供 Amazon CloudWatch 指標。
群組會根據名稱或 Amazon Resource Name (ARN) 進行識別，且包含篩選條件表達式。此服務會比較傳入表達式的追蹤，並依序存放。
您可以在下拉式功能表，篩選條件表達式左側的搜尋列，建立或修改群組。
**注意**
如果服務驗證群組資格時發生錯誤，該群組即不會處理傳入的追蹤，且會記錄錯誤指標。
如需 群組的詳細資訊，請參閱 [設定 群組](xray-console-groups.md)。
## 篩選條件表達式語法
篩選條件表達式可以包含「關鍵字」**、一元或二元「運算子」**以及用於比較的「值」**。
```
keyword operator value
```
不同運算子適用於不同類型的關鍵字。例如，`responsetime` 是數字關鍵字，可相較於與數字相關的運算子。
**Example – 回應時間大於 5 秒的請求**
```
responsetime > 5
```
您可以使用 `AND` 或 `OR` 運算子，將多個表達式結合成一個複合表達式。
**Example – 總持續時間為 5-8 秒的請求**
```
duration >= 5 AND duration <= 8
```
簡單關鍵字和運算子只能發現追蹤層級的問題。如果下游發生錯誤，但已由您的應用程式處理而未傳回給使用者，搜尋 `error` 時就不會找到此錯誤。
若要尋找含有下游問題的追蹤，您可以使用[複雜的關鍵字](#console-filters-complex) `service()` 和 `edge()`。這些關鍵字可讓您將篩選條件表達式套用到所有下游節點、單一下游節點，或是兩個節點之間的邊緣。如需更高的精細程度，您可以依據 [id() 函數](#console-filters-functions)類型來篩選服務和邊緣。
## 布林值關鍵字
布林值關鍵字值可為 true 或 false。使用這些關鍵字來尋找導致錯誤的追蹤。
**布林值關鍵字**
+ `ok` – 回應狀態碼為 2XX 成功。
+ `error` – 回應狀態碼為 4XX 用戶端錯誤。
+ `throttle` – 回應狀態碼為 429 太多請求。
+ `fault` – 回應狀態碼為 5XX 伺服器錯誤。
+ `partial` – 請求的區段不完整。
+ `inferred` – 請求已推斷客群。
+ `first` – Element 是列舉清單的第一個。
+ `last` – Element 是列舉清單的最後一個。
+ `remote` – 根本原因實體為遠端。
+ `root` – 服務是追蹤的進入點或根區段。
布林值運算子可尋找指定索引鍵為 `true` 或 `false` 的區段。
**布林值運算子**
+ none – 如果關鍵字為 true，則表達式為 true。
+ `!` – 如果關鍵字為 false，表示表達式為 true。
+ `=`，`!=` – 將關鍵字的值與字串`true`或 進行比較`false`。這些運算子的作用與其他運算子相同，但更加明確。
**Example – 回應狀態為 2XX OK**
```
ok
```
**Example – 回應狀態不是 2XX OK**
```
!ok
```
**Example – 回應狀態不是 2XX OK**
```
ok = false
```
**Example – 最後一個列舉的錯誤追蹤具有錯誤名稱 "deserialize"**
```
rootcause.fault.entity { last and name = "deserialize" }
```
**Example – 具有遠端區段的請求，涵蓋範圍大於 0.7 且服務名稱為 "traces"**
```
rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" }
```
**Example – 具有推斷客群的請求，其中服務類型為「AWS：DynamoDB」**
```
rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" }
```
**Example – 具有名為 "data-plane" 作為根的客群的請求**
```
service("data-plane") {root = true and fault = true}
```
## 數字關鍵字
使用數字關鍵字以搜尋含特定回應時間、持續時間或回應狀態的請求。
**數字關鍵字**
+ `responsetime` – 伺服器傳送回應所花費的時間。
+ `duration` – 請求總持續時間，包括所有下游呼叫。
+ `http.status` – 回應狀態碼。
+ `index` – 列舉清單中 元素的位置。
+ `coverage` – 實體回應時間相對於根區段回應時間的十進位百分比。僅適用於回應時間根本原因實體。
**數字運算子**
數字關鍵字使用標準的對等和比較運算子。
+ `=`，`!=` – 關鍵字等於或不等於數值。
+ `<`、`<=``>`、 `>=`- 關鍵字小於或等於數值。
**Example – 回應狀態不是 200 OK**
```
http.status != 200
```
**Example – 總持續時間為 5-8 秒的請求**
```
duration >= 5 AND duration <= 8
```
**Example – 在不到 3 秒內成功完成的請求，包括所有下游呼叫**
```
ok !partial duration <3
```
**Example – 索引大於 5 的列舉清單實體**
```
rootcause.fault.service { index > 5 }
```
**Example – 涵蓋範圍大於 0.8 的最後一個實體的請求**
```
rootcause.responsetime.entity { last and coverage > 0.8 }
```
## 字串關鍵字
使用字串關鍵字以尋找請求標頭中含特定文字或特定使用者 ID 的追蹤。
**字串關鍵字**
+ `http.url` – 請求 URL。
+ `http.method` – 請求方法。
+ `http.useragent` – 請求使用者代理程式字串。
+ `http.clientip` – 申請者的 IP 地址。
+ `user` – 追蹤中任何區段的使用者欄位值。
+ `name` – 服務或例外狀況的名稱。
+ `type` – 服務類型。
+ `message` – 例外狀況訊息。
+ `availabilityzone` – 追蹤中任何區段的 availabilityzone 欄位值。
+ `instance.id` – 追蹤中任何區段上執行個體 ID 欄位的值。
+ `resource.arn` – 追蹤中任何區段上資源 ARN 欄位的值。
字串運算子可尋找等於或包含特定文字的值。您必須一律在引號中指定值。
**字串運算子**
+ `=`，`!=` – 關鍵字等於或不等於數值。
+ `CONTAINS` – 關鍵字包含特定字串。
+ `BEGINSWITH` ， `ENDSWITH` – 關鍵字以特定字串開頭或結尾。
**Example – http.url 篩選條件**
```
http.url CONTAINS "/api/game/"
```
若要測試追蹤上是否存在欄位 (無論其值為何)，請檢查欄位是否包含空白字串。
**Example – 使用者篩選條件**
尋找所有含使用者 ID 的追蹤。
```
user CONTAINS ""
```
**Example – 選取具有故障根本原因的追蹤，其中包含名為 "Auth" 的服務**
```
rootcause.fault.service { name = "Auth" }
```
**Example – 選取具有回應時間根本原因的追蹤，其上次服務具有 DynamoDB 類型**
```
rootcause.responsetime.service { last and type = "AWS::DynamoDB" }
```
**Example – 選取具有故障根本原因的追蹤，其上次例外狀況具有「account\$1id 存取遭拒：1234567890」訊息**
```
rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890"
```
## 複雜關鍵字
使用複雜關鍵字以根據服務名稱、邊緣名稱或註釋值來尋找請求。若是服務和邊緣，您可以指定額外篩選條件表達式以套用到服務或邊緣。若是註釋，您可以使用布林值、數字或字串運算子，篩選含特定索引鍵的註釋值。
**複雜關鍵字**
+ `annotation[key]` – 具有欄位*索引鍵*的註釋值。註釋值可以是布林值、數字或字串，所以您可以使用任何這些類型的比較運算子。您可以將此關鍵字與 `service`或 `edge`關鍵字結合使用。包含點 （句點） 的註釋索引鍵必須以方括號 (**【 】**) 包裝。
+ `edge(source, destination) {filter}` – 服務*來源*和*目的地*之間的連線。選用的大括號可包含篩選表達式，以套用到此連線的服務。
+ `group.name / group.arn` – 群組篩選條件表達式的值，由群組名稱或群組 ARN 參考。
+ `json` – JSON 根本原因物件。如需以程式設計方式建立 JSON 實體的步驟，請參閱[從 AWS X-Ray 取得資料](xray-api-gettingdata.md)。
+ `service(name) {filter}` – 具有*名稱*的服務。選用的大括號可包含篩選表達式，以套用到服務所建立的區段。
使用 服務關鍵字來尋找針對追蹤映射上特定節點之請求的追蹤。
複雜關鍵字運算子會尋找已設定或未設定指定金鑰的區段。
**複雜關鍵字運算子**
+ none – 如果已設定關鍵字，則表達式為 true。如果關鍵字為布林值類型，則會評估為布林值。
+ `!` – 若未設定關鍵字，表示表達式為 true。如果關鍵字為布林值類型，則會評估為布林值。
+ `=`，`!=` – 比較關鍵字的值。
+ `edge(source, destination) {filter}` – 服務*來源*和*目的地*之間的連線。選用的大括號可包含篩選表達式，以套用到此連線的服務。
+ `annotation[key]` – 具有欄位*索引鍵*的註釋值。註釋值可以是布林值、數字或字串，所以您可以使用任何這些類型的比較運算子。您可以將此關鍵字與 `service`或 `edge`關鍵字結合使用。
+ `json` – JSON 根本原因物件。如需以程式設計方式建立 JSON 實體的步驟，請參閱[從 AWS X-Ray 取得資料](xray-api-gettingdata.md)。
使用 服務關鍵字來尋找針對追蹤映射上特定節點之請求的追蹤。
**Example – 服務篩選條件**
包含對 `api.example.com` 的呼叫且發生故障 (500 系列錯誤) 的請求。
```
service("api.example.com") { fault }
```
您可以排除服務名稱，以將篩選條件表達式套用到服務地圖中的所有節點。
**Example – 服務篩選條件**
造成追蹤映射上任何位置故障的請求。
```
service() { fault }
```
邊緣關鍵字可將篩選條件表達式套用到兩個節點之間的連線。
**Example – 邊緣篩選條件**
`api.example.com` 服務對 `backend.example.com` 發出呼叫但因錯誤而失敗的請求。
```
edge("api.example.com", "backend.example.com") { error }
```
您也可以搭配使用 `!` 運算子與服務和邊緣關鍵字，以排除其他篩選條件表達式結果的服務或邊緣。
**Example – 服務和請求篩選條件**
URL 開頭為 `http://api.example.com/` 並包含 `/v2/` 但未到達名稱為 `api.example.com` 之服務的請求。
```
http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com")
```
**Example – 服務和回應時間篩選條件**
尋找`http url`設定 且回應時間大於 2 秒的追蹤。
```
http.url AND responseTime > 2
```
對於註釋，您可以呼叫`annotation[key]`設定 的所有追蹤，或使用對應於 值類型的比較運算子。
**Example – 註釋與字串值**
含名稱為 `gameid`、字串值為 `"817DL6VO"` 之註釋的請求。
```
annotation[gameid] = "817DL6VO"
```
**Example – 已設定註釋**
具有名為 `age` 集合的註釋的請求。
```
annotation[age]
```
**Example – 未設定註釋**
沒有已命名註釋`age`集的請求。
```
!annotation[age]
```
**Example – 註釋與數值**
含註釋存留期且數值大於 29 的請求。
```
annotation[age] > 29
```
**Example – 註釋結合服務或邊緣**
```
service { annotation[request.id] = "917DL6VO" }
```
```
edge { source.annotation[request.id] = "916DL6VO" }
```
```
edge { destination.annotation[request.id] = "918DL6VO" }
```
**Example – 具有使用者的 群組**
追蹤符合`high_response_time`群組篩選條件 （例如 `responseTime > 3`) 且使用者名為 Alice 的請求。
```
group.name = "high_response_time" AND user = "alice"
```
**Example – 具有根本原因實體的 JSON**
有相符根本原因實體的請求。
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
## id 函數
當您將服務名稱提供給 `service` 或 `edge` 關鍵字時，您可取得具有該名稱之所有節點的結果。如需更精確的篩選，除了名稱之外，您還可以使用 `id` 函數來指定服務類型，以區分名稱相同的節點。
檢視監控帳戶中多個帳戶的追蹤時，請使用 `account.id`函數指定服務的特定帳戶。
```
id(name: "service-name", type:"service::type", account.id:"account-ID")
```
您可以使用 `id` 函數來代替服務和邊緣篩選條件中的服務名稱。
```
service(id(name: "service-name", type:"service::type")) { filter }
```
```
edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter }
```
例如， AWS Lambda 函數會在追蹤映射中產生兩個節點；一個用於函數叫用，另一個用於 Lambda 服務。這兩個節點的名稱相同，但類型不同。標準的服務篩選條件可尋找這兩種追蹤。
**Example – 服務篩選條件**
包含任何名為 `random-name` 服務上的錯誤的請求。
```
service("random-name") { error }
```
使用 `id` 函數來縮小搜尋範圍至函數本身的錯誤，而不含服務的錯誤。
**Example – 具有 ID 函數的服務篩選條件**
包含名為 `random-name`、類型為 `AWS::Lambda::Function` 服務上的錯誤的請求。
```
service(id(name: "random-name", type: "AWS::Lambda::Function")) { error }
```
若要依據類型來搜尋節點，您也可以完全排除名稱。
**Example – 具有 ID 函數和服務類型的服務篩選條件**
包含類型為 `AWS::Lambda::Function` 服務上的錯誤的請求。
```
service(id(type: "AWS::Lambda::Function")) { error }
```
若要搜尋特定節點 AWS 帳戶，請指定帳戶 ID。
**Example – 具有 ID 函數和帳戶 ID 的服務篩選條件**
在特定帳戶 ID 內包含服務的請求`AWS::Lambda::Function`。
```
service(id(account.id: "account-id"))
```
# 跨帳戶追蹤
AWS X-Ray 支援*跨帳戶可觀測性*，可讓您監控和故障診斷 中跨多個帳戶的應用程式 AWS 區域。您可以順暢地搜尋、視覺化和分析任何連結帳戶中的指標、日誌和追蹤，就像您在單一帳戶中操作一樣。這提供跨多個帳戶周遊的請求的完整檢視。您可以在 [CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)的 X-Ray 追蹤地圖和追蹤頁面中檢視跨帳戶追蹤。
共用的可觀測性資料可包含下列任一類型的遙測：
+ Amazon CloudWatch 中的指標
+ Amazon CloudWatch Logs 中的日誌群組
+ 中的追蹤 AWS X-Ray
+ Amazon CloudWatch Application Insights 中的應用程式
## 設定跨帳戶可觀測性
若要開啟跨帳戶可觀測性，請設定一或多個 AWS *監控*帳戶，並將其連結至多個*來源*帳戶。監控帳戶是中央帳戶 AWS 帳戶 ，可檢視來源帳戶產生的可觀測性資料並與之互動。來源帳戶是針對其中包含的資源 AWS 帳戶 產生可觀測性資料的個人。
來源帳戶與監控帳戶共用其可觀測性資料。追蹤會從每個來源帳戶複製到最多五個監控帳戶。從來源帳戶到第一個監控帳戶的追蹤複本是免費的。傳送至其他監控帳戶的追蹤複本會根據標準定價，向每個來源帳戶收費。如需詳細資訊，請參閱 [AWS X-Ray 定價](https://aws.amazon.com/xray/pricing/)和 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。
若要在監控帳戶和來源帳戶之間建立連結，請使用 CloudWatch 主控台或 AWS CLI 和 API 中的新可觀測性存取管理員命令。如需詳細資訊，請參閱 [CloudWatch 跨帳戶觀察功能](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)。
**注意**
X-Ray 追蹤的計費方式是收到追蹤 AWS 帳戶 的 。如果[抽樣](xray-concepts.md#xray-concepts-sampling)請求跨越多個 服務 AWS 帳戶，每個帳戶都會記錄個別的追蹤，且所有追蹤都會共用相同的追蹤 ID。若要進一步了解跨帳戶可觀測性定價，請參閱[AWS X-Ray 定價](https://aws.amazon.com/xray/pricing/)和 [Amazon CloudWatch 定價](https://aws.amazon.com/cloudwatch/pricing/)。
## 檢視跨帳戶追蹤
跨帳戶追蹤會顯示在監控帳戶中。每個來源帳戶只會顯示該特定帳戶的本機追蹤。下列各節假設您已登入監控帳戶，並已開啟 Amazon CloudWatch 主控台。在追蹤地圖和追蹤頁面上，監控帳戶徽章會顯示在右上角。
![\[監控帳戶徽章\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/crossaccount-monitoring-account.png)
### 追蹤映射
在 CloudWatch 主控台中，從左側導覽窗格選擇 **X-Ray 追蹤**下的追蹤**映射**。根據預設，追蹤映射會顯示所有來源帳戶的節點，這些來源帳戶會將追蹤傳送至監控帳戶，以及監控帳戶本身的節點。在追蹤映射上，選擇左上角**的篩選條件**，使用**帳戶**下拉式清單篩選追蹤映射。套用帳戶篩選條件後，來自不符合目前篩選條件之帳戶的 服務節點會顯示為灰色。
![\[篩選的追蹤映射\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/crossaccount-servicemap-account-filter.png)
當您選擇服務節點時，節點詳細資訊窗格會包含服務的帳戶 ID 和標籤。
![\[節點詳細資訊窗格\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/crossaccount-servicemap-node-detail.png)
在追蹤映射的右上角，選擇**清單檢視**以查看服務節點清單。服務節點清單包含來自監控帳戶和所有已設定來源帳戶的 服務。從節點篩選條件中選擇節點，依**帳戶標籤**或**帳戶 ID** **篩選節點**清單。
![\[篩選的服務清單\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/crossaccount-servicelist-account-filter.png)
### 追蹤
從監控帳戶開啟 CloudWatch 主控台，然後在左側導覽窗格中的 X-Ray 追蹤下選擇**追蹤**，以檢視跨多個帳戶的追蹤詳細資訊。 ****您也可以在 X-Ray **追蹤地圖**中選擇節點，然後從節點詳細資訊窗格中選擇**檢視追蹤**，以開啟此頁面。
**追蹤**頁面支援依帳戶 ID 查詢。若要開始使用，[請輸入包含一或多個帳戶 ID 的查詢](xray-console-filters.md)。 IDs 下列範例查詢已透過帳戶 ID X * *或 *Y* 傳遞的追蹤：
```
service(id(account.id:"X")) OR service(id(account.id:"Y"))
```
![\[依帳戶查詢追蹤\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/crossaccount-traces-query-by-account.png)
依**帳戶**精簡查詢。從清單中選擇一或多個帳戶，然後選擇**新增至查詢**。
![\[依帳戶精簡追蹤查詢\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/crossaccount-traces-refine-by-account.png)
### 追蹤詳細資訊
從追蹤頁面底部的**追蹤**清單中選擇追蹤，以檢視**追蹤**的詳細資訊。**追蹤詳細資訊**隨即顯示，包括追蹤詳細資訊映射來自所有帳戶的服務節點，而這些帳戶已傳遞追蹤。選擇特定的服務節點以查看其對應的帳戶。
**客群時間軸**區段會顯示時間軸中每個客群的帳戶詳細資訊。
![\[區段時間軸\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/crossaccount-traces-segment-timeline.png)
# 追蹤事件驅動型應用程式
AWS X-Ray 支援使用 Amazon SQS 和 追蹤事件驅動型應用程式 AWS Lambda。使用 CloudWatch 主控台查看與 Amazon SQS 佇列且由一或多個 Lambda 函數處理的每個請求的連線檢視。來自上游訊息生產者的追蹤會自動連結至來自下游 Lambda 消費者節點的追蹤，建立end-to-end檢視。
**注意**
每個追蹤區段最多可連結至 20 個追蹤，而追蹤最多可包含 100 個連結。在某些情況下，連結其他追蹤可能會導致超過[追蹤文件大小上限](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)，進而導致追蹤可能不完整。例如，當啟用追蹤的 Lambda 函數在單一調用中將許多 SQS 訊息傳送至佇列時，可能會發生這種情況。如果您遇到此問題，可以使用 X-Ray SDKs進行緩解。如需詳細資訊，請參閱適用於 [Java](https://github.com/aws/aws-xray-sdk-java#oversampling-mitigation)、[Node.js](https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core#oversampling-mitigation)、[Python](https://github.com/aws/aws-xray-sdk-python#oversampling-mitigation)、[Go](https://github.com/aws/aws-xray-sdk-go#oversampling-mitigation) 或 [.NET](https://github.com/aws/aws-xray-sdk-dotnet#oversampling-mitigation) 的 X-Ray 開發套件。
## 在追蹤映射中檢視連結的追蹤
使用 [CloudWatch 主控台](https://console.aws.amazon.com/cloudwatch/)中的**追蹤映射**頁面，檢視追蹤映射，其中包含來自訊息生產者且連結至 Lambda 消費者追蹤的追蹤。這些連結會以虛線邊緣顯示，以連接 Amazon SQS 節點和下游 Lambda 取用者節點。
![\[Amazon SQS 和 Lambda 節點之間的邊緣。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-servicemap-linkededge.png)
選取虛線邊緣以顯示*收到的事件存*留期長條圖，其會映射消費者收到事件存留期的分散。每次收到事件時都會計算存留期。
![\[包含已接收事件存留期長條圖的邊緣。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-servicemap-linkededgedetails-cw.png)
## 檢視連結的追蹤詳細資訊
**檢視從訊息生產者、Amazon SQS 佇列或 Lambda 取用者傳送的追蹤詳細資訊：**
1. 使用**追蹤地圖**來選取訊息生產者、Amazon SQS 或 Lambda 取用者節點。
1. 從節點詳細資訊窗格中選擇**檢視追蹤**，以顯示追蹤清單。您也可以直接導覽至 CloudWatch 主控台中的**追蹤**頁面。
1. 從清單中選擇特定追蹤，以開啟追蹤詳細資訊頁面。當選取的追蹤是一組連結追蹤的一部分時，追蹤詳細資訊頁面會顯示訊息。
![\[連結的追蹤詳細資訊\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-tracedetails-header.png)
追蹤詳細資訊映射會顯示目前的追蹤，以及上游和下游連結追蹤，每個追蹤都包含在指示每個追蹤邊界的方塊中。如果目前選取的追蹤連結至多個上游或下游追蹤，則會堆疊上游或下游連結追蹤內的節點，並顯示**選取追蹤**按鈕。
![\[多個連結的上游追蹤\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-tracedetails-tracemap.png)
在追蹤詳細資訊映射下方，會顯示追蹤區段的時間軸，包括上游和下游連結追蹤。如果有多個上游或下游連結追蹤，則無法顯示其區段詳細資訊。若要檢視一組連結追蹤中單一追蹤的區段詳細資訊，[請選取單一追蹤](#xray-tracelinking-filterbatch)，如下所述。
![\[顯示連結追蹤的區段時間軸\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-tracedetails-timeline.png)
## 在一組連結追蹤中選取單一追蹤
**將一組連結的追蹤篩選為單一追蹤，以查看時間軸中的區段詳細資訊。**
1. 選擇**追蹤詳細資訊地圖上連結追蹤下方的選取**追蹤。追蹤清單隨即顯示。
![\[連結的追蹤清單\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-tracedetails-tracelist.png)
1. 選取追蹤旁的選項按鈕，以在追蹤詳細資訊映射中檢視。
1. 選擇**取消追蹤選擇**，以檢視整組連結的追蹤。
![\[單一連結追蹤\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-batch-tracedetails-filteredbatch.png)
# 使用延遲長條圖
當您在 AWS X-Ray [追蹤映射](xray-console-servicemap.md)上選取節點或邊緣時，X-Ray 主控台會顯示延遲分佈長條圖。
## Latency (延遲)
延遲是指請求開始和完成之間的時間。長條圖中顯示了延遲分佈。它會在 x 軸上顯示持續時間，在 y 軸上顯示符合每個持續時間的請求百分比。
此長條圖顯示的服務可在 300 毫秒內完成大多數請求。少許百分比的請求花費最多 2 秒，以及幾個異常值花費更多時間。
![\[延遲長條圖，其 x 軸上顯示持續時間，y 軸上顯示每個持續時間的請求百分比\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-histogram.png)
## 解譯服務詳細資訊
服務長條圖和邊緣長條圖可從服務或申請者的角度，提供延遲的視覺化呈現。
+ 按一下圓圈以選擇*服務節點*。X-Ray 會顯示服務所服務請求的長條圖。延遲是由服務記錄的延遲，且不包含任何服務和申請者之間的網路延遲。
+ 按一下兩個服務之間的*邊緣*線或箭頭尖端，以選擇邊緣。X-Ray 會顯示由下游服務所提供服務之請求者的請求長條圖。這些延遲是由申請者記錄的延遲，且包含兩個服務之間的網路連線延遲。
若要解譯 **Service details (服務詳細資訊)** 長條圖，您可以尋找與長條圖中大多數值差異最大的值。您可將這些「異常值」**視為長條圖中的峰值，並檢視特定區域的追蹤資料以調查發生的情況。
若要查看依延遲篩選的追蹤，請在長條圖上選取範圍。按一下您想要選擇的起點位置，並從左到右拖曳，將要包含在追蹤篩選條件中的延遲範圍反白顯示。
![\[選取範圍以檢視追蹤，方法是按一下起點位置，並從左到右拖曳以建立追蹤篩選條件的範圍\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-selection.png)
選取範圍之後，您可以選擇 **Zoom (縮放)**，以僅檢視部分長條圖並縮小您的選擇範圍。
![\[選擇 Zoom (縮放) 以檢視長條圖中的選取範圍\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-zoom.png)
一旦您設定好所需的焦點區域時，請選擇 **View traces (檢視追蹤)**。
# 使用 X-Ray 洞察
AWS X-Ray 會持續分析您帳戶中的追蹤資料，以識別應用程式中出現的問題。當錯誤率超過預期範圍時，它會建立洞*見*，記錄問題並追蹤其影響，直到問題解決為止。透過洞察，您可以：
+ 識別應用程式問題發生的位置、問題的根本原因，以及相關的影響。洞見提供的影響分析可讓您衍生問題的嚴重性和優先順序。
+ 當問題隨時間變更時接收通知。Insights 通知可以使用 Amazon EventBridge 與您的監控和提醒解決方案整合。此整合可讓您根據問題的嚴重性來傳送自動電子郵件或提醒。
X-Ray 主控台會在追蹤映射中識別具有持續事件的節點。若要查看洞見的摘要，請選擇受影響的節點。您也可以從左側的導覽窗格中選擇 **Insights** 來檢視和篩選洞見。
![\[使用洞見摘要追蹤地圖節點。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-insights-servicemap.png)
當 X-Ray 在服務映射的一或多個節點中偵測到*異常*時，會建立洞見。此服務使用統計建模來預測應用程式中服務的預期錯誤率。在上述範例中，異常是來自 的故障增加 AWS Elastic Beanstalk。Elastic Beanstalk 伺服器發生多個 API 呼叫逾時，導致下游節點異常。
## 在 X-Ray 主控台中啟用洞見
必須針對您要使用洞見功能的每個群組啟用洞見。您可以從**群組**頁面啟用洞見。
1. 開啟 [X-Ray 主控台](https://console.aws.amazon.com/xray/home#)。
1. 選取現有的群組，或選擇**建立群組來建立新的群組**，然後選取**啟用洞見**。如需在 X-Ray 主控台中設定群組的詳細資訊，請參閱 [設定 群組](xray-console-groups.md)。
1. 在左側導覽窗格中，選擇 **Insights**，然後選擇要檢視的洞見。
![\[X-Ray 主控台中的洞見清單。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-insights.png)
**注意**
X-Ray 使用 GetInsightSummaries、GetInsight、GetInsightEvents 和 GetInsightImpactGraph API 操作從洞見擷取資料。
如需詳細資訊，請參閱[AWS X-Ray 如何使用 IAM](security_iam_service-with-iam.md)。
## 啟用洞見通知
透過洞見通知，會為每個洞見事件建立通知，例如當洞見建立、大幅變更或關閉時。客戶可以透過 Amazon EventBridge 事件接收這些通知，並使用條件式規則採取動作，例如 SNS 通知、Lambda 調用、將訊息發佈至 SQS 佇列，或任何 EventBridge 支援的目標。Insights 通知會盡最大努力發出，但不保證。如需目標的詳細資訊，請參閱 [Amazon EventBridge 目標](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.html)。
您可以從群組****頁面為任何已啟用洞察的群組啟用洞察通知。
**啟用 X-Ray 群組的通知**
1. 開啟 [X-Ray 主控台](https://console.aws.amazon.com/xray/home#)。
1. 選擇建立群組來選取**現有群組或建立新的群組**，確保已選取**啟用洞見**，然後選取**啟用通知**。如需在 X-Ray 主控台中設定群組的詳細資訊，請參閱 [設定 群組](xray-console-groups.md)。
**設定 Amazon EventBridge 條件式規則**
1. 開啟 [Amazon EventBridge 主控台](https://console.aws.amazon.com/events/home)。
1. 導覽至左側導覽列中的**規則**，然後選擇**建立規則**。
1. 提供規則的名稱和描述。
1. 選擇**事件模式**，然後選擇**自訂模式**。提供包含 `"source": [ "aws.xray" ]`和 的模式`"detail-type": [ "AWS X-Ray Insight Update" ]`。以下是一些可能模式的範例。
+ 符合 X-Ray 洞察中所有傳入事件的事件模式：
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ]
}
```
+ 符合指定 **state**和 的事件模式**category**：
```
{
"source": [ "aws.xray" ],
"detail-type": [ "AWS X-Ray Insight Update" ],
"detail": {
"State": [ "ACTIVE" ],
"Category": [ "FAULT" ]
}
}
```
1. 選取並設定當事件符合此規則時，您要叫用的目標。
1. （選用） 提供標籤以更輕鬆地識別和選取此規則。
1. 選擇**建立**。
**注意**
X-Ray 洞察通知會將事件傳送至目前不支援客戶受管金鑰的 Amazon EventBridge。如需詳細資訊，請參閱[中的資料保護 AWS X-Ray](xray-console-encryption.md)。
## Insight 概觀
洞見的概觀頁面會嘗試回答三個關鍵問題：
+ 基礎問題是什麼？
+ 根本原因是什麼？
+ 有什麼影響？
**異常服務**區段會顯示每個服務的時間表，說明事件期間的錯誤率變更。時間軸顯示覆蓋在實心頻帶上故障的追蹤數目，根據記錄的流量來指出預期的故障數目。洞見的持續時間由*事件視窗*視覺化。當 X-Ray 觀察到指標變得異常並在洞見作用中時持續存在時，事件時段就會開始。
下列範例顯示導致事件的故障增加：
![\[X-Ray 洞見的概觀頁面。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-insights-overview.png)
**根本原因**區段顯示著重於根本原因服務和受影響路徑的追蹤映射。您可以透過選取根本原因映射右上角的眼睛圖示來隱藏未受影響的節點。根本原因服務是 X-Ray 識別異常的最遠下游節點。它可以代表您檢測的服務，或您的服務透過檢測的用戶端呼叫的外部服務。例如，如果您使用經檢測的 AWS SDK 用戶端呼叫 Amazon DynamoDB，DynamoDB 的故障增加會導致 DynamoDB 作為根本原因的洞見。
若要進一步調查根本原因，請選取**根本原因圖表上的檢視根本原因詳細資訊**。您可以使用**分析**頁面來調查根本原因和相關訊息。如需詳細資訊，請參閱[與 Analytics 主控台互動](xray-console-analytics.md)。
![\[X-Ray 洞見的概觀頁面。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-insights-root-cause.png)
在地圖中繼續上游的故障可能會影響多個節點並導致多個異常。如果故障一直傳遞給發出請求的使用者，則結果是*用戶端故障*。這是追蹤映射根節點中的錯誤。**影響**圖表提供整個群組的用戶端體驗時間軸。此體驗是根據下列狀態的百分比計算：**Fault**、 **Error**、 **Throttle** 和 **Okay**。
![\[X-Ray 事件的影響圖表。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-insights-impact.png)
此範例顯示在事件發生期間根節點發生故障的追蹤增加。下游服務中的事件不一定對應於用戶端錯誤增加。
選擇**分析洞見**會在視窗中開啟 X-Ray Analytics 主控台，您可以在其中深入了解導致洞見的追蹤集。如需詳細資訊，請參閱[與 Analytics 主控台互動](xray-console-analytics.md)。
**了解影響**
AWS X-Ray 會測量持續問題所造成的影響，做為產生洞見和通知的一部分。影響的測量方式有兩種：
+ 對 X-Ray [群組](xray-console-groups.md)的影響
+ 對根本原因服務的影響
此影響取決於在特定期間內失敗或導致錯誤的請求百分比。此影響分析可讓您根據特定案例衍生問題的嚴重性和優先順序。除了洞察通知之外，此影響也可作為主控台體驗的一部分。
**重複資料刪除**
AWS X-Ray 洞見可消除多個微服務的問題。它使用異常偵測來判斷問題根本原因的服務、判斷其他相關服務是否因相同的根本原因而出現異常行為，並將結果記錄為單一洞見。
## 檢閱洞見的進度
X-Ray 會定期重新評估洞見，直到問題解決為止，並將每個值得注意的中繼變更記錄為[通知](#xray-console-insight-notifications)，可做為 Amazon EventBridge 事件傳送。這可讓您建置程序和工作流程，以判斷問題如何隨著時間而變更，並採取適當的動作，例如傳送電子郵件或使用 EventBridge 與提醒系統整合。
您可以在**檢查**頁面**的影響時間軸**中檢閱事件。根據預設，時間軸會顯示最受影響的服務，直到您選擇不同的服務為止。
![\[檢查具有影響時間軸的頁面。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-insights-inspect.png)
若要查看事件的追蹤映射和圖形，請從影響時間軸中選擇它。追蹤映射會顯示應用程式中受事件影響的服務。在**影響分析**下，圖形會顯示所選節點和群組中用戶端的故障時間表。
![\[X-Ray 洞見的影響分析圖表。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/console-insights-inspect-analysis.png)
若要深入了解事件中涉及的追蹤，請在**檢查**頁面上選擇**分析事件**。您可以使用**分析**頁面來精簡追蹤清單，並識別受影響的使用者。如需詳細資訊，請參閱[與 Analytics 主控台互動](xray-console-analytics.md)。
# 與 Analytics 主控台互動
AWS X-Ray Analytics 主控台是一種互動式工具，可用來解譯追蹤資料，以快速了解應用程式及其基礎服務的效能。主控台可讓您透過互動的回應時間和時間序列圖表，探索、分析和視覺化追蹤。
在 Analytics 主控台中選取選項時，主控台會建構篩選條件以反映所有追蹤的所選子集。您可以按一下與目前追蹤集相關聯之指標和欄位的圖表和面板，使用愈益精細的篩選條件來精簡作用中的資料集。
**Topics**
+ [主控台功能](#xray-console-analytics-features)
+ [回應時間分佈](#xray-console-analytics-response)
+ [時間序列活動](#xray-console-analytics-time)
+ [工作流程範例](#xray-console-analytics-workflows)
+ [觀察服務圖中的故障](#xray-console-analytics-observe-faults)
+ [識別回應時間高峰](#xray-console-analytics-response-peaks)
+ [檢視有狀態碼標記的所有追蹤](#xray-console-analytics-response-peaks)
+ [檢視在子群組中並與使用者相關聯的所有項目](#xray-console-analytics-subgroups)
+ [比較兩個具有不同篩選標準的追蹤集](#xray-console-analytics-compare)
+ [識別感興趣的追蹤以及檢視其詳細資訊](#xray-console-analytics-identify)
## 主控台功能
X-Ray Analytics 主控台使用下列主要功能來分組、篩選、比較和量化追蹤資料。
### 功能
| 功能 | 描述 |
| --- | --- |
| **Groups (群組)** | 最初選取的群組是 `Default`。若要變更已擷取的群組，請從主要篩選條件表達式搜尋列右側的選單中，選取不同的群組。若要進一步了解群組，請參閱[搭配使用篩選條件表達式與群組](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html#groups)。 |
| **Retrieved traces (已擷取的追蹤)** | 根據預設，Analytics 主控台會根據所選群組中的所有追蹤產生圖表。已擷取的追蹤代表您工作集中的所有追蹤。您可在此圖標中找到追蹤計數。您套用到主要搜尋列的篩選條件表達式會精簡並更新擷取的追蹤。 |
| **Show in charts/Hide from charts (在圖表中顯示/隱藏)** | 切換比較作用中的群組和已擷取的追蹤。若要針對任何作用中的篩選條件比較群組的相關資料，請選擇 **Show in charts (在圖表中顯示)**。若要從圖表中移除此檢視，請選擇 **Hide from charts (在圖表中隱藏)**。 |
| **Filtered trace set A (篩選過的追蹤集 A)** | 透過與圖形和資料表的互動，套用篩選條件來建立**已篩選追蹤集 A** 的條件。 套用篩選條件時，會從此圖磚中計算適用的追蹤數量，以及擷取的追蹤總數百分比。在 **Filtered trace set A (篩選過的追蹤集 A)** 圖標中，篩選條件填入為標籤，也可自圖標中移除。 |
| **Refine (精簡)** | 此功能會根據套用到追蹤集 A 的篩選條件，更新擷取的追蹤集。縮小擷取的追蹤集範圍會更新根據追蹤集 A 篩選條件擷取之所有追蹤的初步集合。已擷取追蹤的初步集合是群組中所有追蹤的抽樣子集。 |
| **Filtered trace set B (篩選過的追蹤集 B)** | 建立時，**篩選的追蹤集 B** 是**篩選的追蹤集 A** 的副本。 若要比較兩個追蹤集，請進行新的篩選條件選擇，以套用至追蹤集 B，而追蹤集 A 保持固定。套用篩選條件後，就會在此圖標內計算擷取自總量的適用追蹤數目與追蹤百分比。在 **Filtered trace set B (篩選過的追蹤集 B)** 圖標中，篩選條件填入為標籤，也可自圖標中移除。 |
| **Response time root cause entity paths (回應時間根本原因實體路徑)** | 記錄實體路徑的資料表。X-Ray 會判斷追蹤中哪個路徑最有可能導致回應時間。格式指出實體遇到的階層，以回應時間根本原因結束。使用這些資料列篩選重複出現的回應時間故障。如需自訂根本原因篩選條件以及透過 API 取得資料的詳細資訊，請參閱[擷取和縮小範圍根本原因分析](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-gettingdata.html#xray-api-analytics)。 |
| **Delta (**�**)** | 當追蹤集 A 和追蹤集 B 都為作用中時，新增到指標表的欄。Delta 欄計算追蹤集 A 和追蹤集 B 之間的追蹤百分比差異。 |
## 回應時間分佈
X-Ray Analytics 主控台會產生兩個主要圖形，協助您視覺化追蹤：**回應時間分佈**和**時間序列活動**。本節和下節各提供一個範例，說明閱讀圖表的基本知識。
以下是與回應時間折線圖相關聯的顏色 (時間序列圖使用相同的顏色組合)：
+ **群組中的所有追蹤** – 灰色
+ **擷取的追蹤** – 橘色
+ **篩選的追蹤集 A** – 綠色
+ **篩選的追蹤集 B** – 藍色
**Example – 回應時間分佈**
回應時間分發是顯示特定回應時間追蹤數的圖表。按一下並拖曳，在回應時間分發內選取範圍。這會選取特定回應時間內所有追蹤的 `responseTime` 工作追蹤集，並建立其篩選條件。
![\[顯示追蹤回應時間分佈的圖表。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/analytics-responseTime.png)
## 時間序列活動
時間序列活動圖會顯示特定期間的追蹤數目。顏色指標會鏡像回應時間分發的折線圖顏色。活動序列內的顏色區塊愈深愈滿，表示指定時間內的追蹤愈多。
**Example – 時間序列活動**
按一下並拖曳，在時間序列活動圖中選取範圍。這會選取特定時間範圍內所有追蹤的 `timerange` 工作追蹤集，並建立篩選條件。
![\[選取範圍並建立篩選條件\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/analytics-timeSeries.png)
## 工作流程範例
下列範例顯示 X-Ray Analytics 主控台的常見使用案例。每個範例都會示範主控台體驗的主要功能。因為是群組，所以範例會遵循基本的故障診斷工作流程。這些步驟會逐步解說如何先找出運作狀況不良節點，然後如何與 Analytics 主控台互動，以自動產生比較查詢。一旦透過查詢縮小範圍，您最終會看到特定追蹤的詳細資訊，以判斷是什麼損害伺服器的運作狀況。
## 觀察服務圖中的故障
追蹤映射會根據成功呼叫與錯誤和錯誤的比例，將每個節點的運作狀態著色。當您在節點上看到紅色百分比時，表示有故障。使用 X-Ray Analytics 主控台進行調查。
如需如何讀取追蹤映射的詳細資訊，請參閱[檢視追蹤映射](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap)。
![\[觀察故障\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-2021.png)
## 識別回應時間高峰
使用回應時間分發，您可以觀察回應時間的高峰。只要選取回應時間的高峰，就會更新圖表下方的資料表，公開所有相關聯的指標，例如狀態碼。
當您按一下並拖曳時，X-Ray 會選取並建立篩選條件。它會以灰色陰影顯示在圖形線條的頂部。您現在可以沿著分佈左右拖曳陰影，更新選取範圍和篩選條件。
![\[選取範圍並建立篩選條件\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/analytics-showFilterf.png)
## 檢視有狀態碼標記的所有追蹤
您可以使用圖表下方的指標表，深入了解所選高峰的追蹤。按一下 **HTTP STATUS CODE** 表的資料列，即會自動建立工作資料集的篩選條件。例如，您可以檢視狀態碼為 500 的所有追蹤。這會在追蹤集圖標中建立名為 `http.status` 的篩選條件標籤。
## 檢視在子群組中並與使用者相關聯的所有項目
深入了解以使用者、URL、回應時間根本原因或其他預先定義的屬性為基礎的錯誤集。例如，若要另行篩選狀態碼為 500 的追蹤集，請選取 **USERS (使用者)** 表中的資料列。這會讓追蹤集圖標出現兩個篩選條件標籤：之前已指定的`http.status` 以及 `user`。
## 比較兩個具有不同篩選標準的追蹤集
比較所有不同的使用者及其 POST 請求，尋找其他的差異和關聯性。套用您的第一組篩選條件。它們在回應時間分發中定義為藍色線條。然後選取 **Compare (比較)**。一開始，這會建立追蹤集 A 的篩選條件副本。
若要繼續，請定義一組新的篩選條件，套用到追蹤集 B。這第二組條件會以綠色線條表示。以下範例示範以藍綠顏色組合的不同線條。
![\[折線圖比較\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/analytics-compareLines.png)
## 識別感興趣的追蹤以及檢視其詳細資訊
當您使用主控台篩選條件縮小範圍時，指標表下的追蹤清單就會變得更有意義。追蹤清單表將 **URL**、**USER (使用者)** 和 **STATUS CODE (狀態碼)** 的相關資訊結合到一份檢視中。如需更多詳情，請選取此表的資料列開啟追蹤的 detail (詳細資訊) 頁面，檢視其時間軸和原始資料。
# 設定 群組
群組是一系列追蹤，為篩選條件表達式所定義。您可以使用 群組來產生額外的服務圖表，並提供 Amazon CloudWatch 指標。您可以使用 AWS X-Ray 主控台或 X-Ray API 來建立和管理 服務的群組。本主題說明如何使用 X-Ray 主控台建立和管理群組。如需如何使用 X-Ray API 管理群組的資訊，請參閱 [Groups (群組)](xray-api-configuration.md#xray-api-configuration-groups)。
您可以建立追蹤映射、追蹤或分析的追蹤群組。當您建立群組時，群組會在所有三個頁面上的群組下拉式功能表上變成篩選條件：**追蹤地圖**、**追蹤****和分析**。
![\[群組功能表\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-menu.png)
群組會根據名稱或 Amazon Resource Name (ARN) 進行識別，且包含篩選條件表達式。此服務會比較傳入表達式的追蹤，並依序存放。如需如何建置篩選條件表達式的詳細資訊，請參閱 [使用篩選條件表達式](xray-console-filters.md)。
更新群組的篩選條件表達式不會變更已記錄的資料。更新僅適用於後續追蹤。這會導致圖表合併新舊表達式。若要避免這種情況，請刪除目前的群組並建立新的群組。
**注意**
群組的計費方式是根據符合篩選條件表達式的擷取追蹤。如需詳細資訊，請參閱 [AWS X-Ray 定價](https://aws.amazon.com/xray/pricing/)。
**Topics**
+ [建立群組](#xray-console-group-create-console)
+ [套用群組](#xray-console-group-apply)
+ [編輯群組](#xray-console-group-edit)
+ [複製群組](#xray-console-group-clone)
+ [刪除群組](#xray-console-group-delete)
+ [在 Amazon CloudWatch 中檢視群組指標](#xray-console-group-cloudwatch)
## 建立群組
**注意**
您現在可以從 Amazon CloudWatch 主控台設定 X-Ray 群組。您也可以繼續使用 X-Ray 主控台。
------
#### [ CloudWatch console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在左側導覽窗格中選擇**設定**。
1. 在 **X-Ray 追蹤**區段的**群組**下選擇**檢視設定**。
1. 選擇**群組清單上方的建立**群組。
1. 在**建立群組**頁面上，輸入群組的名稱。群組名稱最多可有 32 個字元，且包含英數字元和破折號。群組名稱區分大小寫。
1. 輸入篩選條件表達式。如需如何建置篩選條件表達式的詳細資訊，請參閱 [使用篩選條件表達式](xray-console-filters.md)。在下列範例中， 群組會篩選來自服務 的故障追蹤`api.example.com`。 和 請求至回應時間大於或等於五秒的服務。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. 在 **Insights** 中，啟用或停用群組的洞見存取。如需洞見的詳細資訊，請參閱[使用 X-Ray 洞察](xray-console-insights.md)。
![\[群組頁面上的洞見核取方塊\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-insights-cw.png)
1. 在**標籤**中，選擇**新增標籤**以輸入標籤索引鍵，也可以選擇輸入標籤值。繼續視需要新增其他標籤。標籤索引鍵必須是唯一的。若要刪除標籤，請選擇每個標籤下方的**移除**。如需標籤的詳細資訊，請參閱[標記 X-Ray 取樣規則和群組](xray-tagging.md)。
![\[群組頁面上的標籤欄位\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-tags-cw.png)
1. 選擇**建立群組**。
------
#### [ X-Ray console ]
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home). 的 X-Ray 主控台。
1. 從左側導覽窗格中的**群組**頁面，或從下列其中一個頁面上的群組選單開啟**建立群組**頁面：**追蹤地圖**、**追蹤****和分析**。
1. 在**建立群組**頁面上，輸入群組的名稱。群組名稱最多可有 32 個字元，且包含英數字元和破折號。群組名稱區分大小寫。
1. 輸入篩選條件表達式。如需如何建置篩選條件表達式的詳細資訊，請參閱 [使用篩選條件表達式](xray-console-filters.md)。在下列範例中， 群組會篩選來自服務 的故障追蹤`api.example.com`。 和 請求至回應時間大於或等於五秒的服務。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. 在 **Insights** 中，啟用或停用群組的洞見存取。如需洞見的詳細資訊，請參閱[使用 X-Ray 洞察](xray-console-insights.md)。
![\[群組頁面上的洞見核取方塊\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-insights.png)
1. 在**標籤**中，輸入標籤索引鍵，並選擇性地輸入標籤值。當您新增標籤時，會顯示新行，供您輸入另一個標籤。標籤索引鍵必須是唯一的。若要刪除標籤，請選擇標籤列結尾的 **X**。如需標籤的詳細資訊，請參閱[標記 X-Ray 取樣規則和群組](xray-tagging.md)。
![\[群組頁面上的標籤欄位\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-tags.png)
1. 選擇**建立群組**。
------
## 套用群組
------
#### [ CloudWatch console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 從 **X-Ray 追蹤**下的導覽窗格開啟下列其中一個頁面：
+ **追蹤映射**
+ **追蹤**
1. 在**依 X-Ray 篩選群組篩選條件中輸入群組**名稱。頁面上顯示的資料會變更為符合 群組中設定的篩選條件表達式。
------
#### [ X-Ray console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) 開啟 X-Ray 主控台。
1. 從導覽窗格開啟下列其中一個頁面：
+ **追蹤映射**
+ **追蹤**
+ **分析**
1. 在群組功能表中，選擇您在 中建立的群組[建立群組](#xray-console-group-create-console)。頁面上顯示的資料會變更為符合 群組中設定的篩選條件表達式。
------
## 編輯群組
------
#### [ CloudWatch console ]
1. 登入 AWS 管理主控台 ，並在 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在左側導覽窗格中選擇**設定**。
1. 在 **X-Ray 追蹤**區段的**群組**下選擇**檢視設定**。
1. 從群組區段中選擇**群組**，然後選擇**編輯**。
1. 雖然您無法重新命名群組，但您可以更新篩選條件表達式。如需如何建置篩選條件表達式的詳細資訊，請參閱 [使用篩選條件表達式](xray-console-filters.md)。在下列範例中， 群組會篩選來自 服務的故障追蹤`api.example.com`，其中請求 URL 地址包含 `example/game`，而請求的回應時間大於或等於五秒。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. 在 **Insights** 中，啟用或停用群組的洞見存取。如需洞見的詳細資訊，請參閱[使用 X-Ray 洞察](xray-console-insights.md)。
![\[群組頁面上的洞見核取方塊\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-insights-cw.png)
1. 在**標籤**中，選擇**新增標籤**以輸入標籤索引鍵，也可以選擇輸入標籤值。繼續視需要新增其他標籤。標籤索引鍵必須是唯一的。若要刪除標籤，請選擇每個標籤下方的**移除**。如需標籤的詳細資訊，請參閱[標記 X-Ray 取樣規則和群組](xray-tagging.md)。
![\[群組頁面上的標籤欄位\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-tags-cw.png)
1. 完成更新群組後，請選擇**更新群組**。
------
#### [ X-Ray console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) 開啟 X-Ray 主控台。
1. 執行下列其中一項操作以開啟**編輯群組**頁面。
1. 在**群組**頁面上，選擇要編輯的群組名稱。
1. 在下列其中一個頁面上的群組選單上，指向群組，然後選擇**編輯**。
+ **追蹤映射**
+ **追蹤**
+ **分析**
1. 雖然您無法重新命名群組，但您可以更新篩選條件表達式。如需如何建置篩選條件表達式的詳細資訊，請參閱 [使用篩選條件表達式](xray-console-filters.md)。在下列範例中， 群組會篩選來自 服務的故障追蹤`api.example.com`，其中請求 URL 地址包含 `example/game`，而請求的回應時間大於或等於五秒。
```
fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5
```
1. 在 **Insights** 中，啟用或停用群組的洞察和洞察通知。如需洞見的詳細資訊，請參閱[使用 X-Ray 洞察](xray-console-insights.md)。
![\[群組頁面上的洞見核取方塊\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-insights.png)
1. 在**標籤**中，編輯標籤索引鍵和值。標籤索引鍵必須是唯一的。標籤值是選用的；如果需要，您可以刪除值。若要刪除標籤，請選擇標籤列結尾的 **X**。如需標籤的詳細資訊，請參閱[標記 X-Ray 取樣規則和群組](xray-tagging.md)。
![\[群組頁面上的標籤欄位\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/group-tags.png)
1. 完成更新群組後，請選擇**更新群組**。
------
## 複製群組
複製群組會建立新的群組，其中包含現有群組的篩選條件表達式和標籤。當您複製群組時，新群組的名稱與其複製的群組相同，並`-clone`附加到名稱。
------
#### [ CloudWatch console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在左側導覽窗格中選擇**設定**。
1. 在 **X-Ray 追蹤**區段的**群組**下選擇**檢視設定**。
1. 從群組區段中選擇**群組**，然後選擇**複製**。
1. 在**建立群組**頁面上，群組的名稱為 *group-name*`-clone`。或者，輸入群組的新名稱。群組名稱最多可有 32 個字元，且包含英數字元和破折號。群組名稱區分大小寫。
1. 您可以保留現有群組的篩選條件表達式，或選擇性地輸入新的篩選條件表達式。如需如何建置篩選條件表達式的詳細資訊，請參閱 [使用篩選條件表達式](xray-console-filters.md)。在下列範例中， 群組會篩選來自服務 的故障追蹤`api.example.com`。 和 請求至回應時間大於或等於五秒的服務。
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. 在**標籤**中，視需要編輯標籤索引鍵和值。標籤索引鍵必須是唯一的。標籤值是選用的；如果需要，您可以刪除值。若要刪除標籤，請選擇標籤列結尾的 **X**。如需標籤的詳細資訊，請參閱[標記 X-Ray 取樣規則和群組](xray-tagging.md)。
1. 選擇**建立群組**。
------
#### [ X-Ray console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) 開啟 X-Ray 主控台。
1. 從左側導覽窗格開啟**群組**頁面，然後選擇您要複製的群組名稱。
1. 從**動作**功能表中選擇**複製群組**。
1. 在**建立群組**頁面上，群組的名稱為 *group-name*`-clone`。或者，輸入群組的新名稱。群組名稱最多可有 32 個字元，且包含英數字元和破折號。群組名稱區分大小寫。
1. 您可以保留現有群組的篩選條件表達式，或選擇性地輸入新的篩選條件表達式。如需如何建置篩選條件表達式的詳細資訊，請參閱 [使用篩選條件表達式](xray-console-filters.md)。在下列範例中， 群組會篩選來自服務 的故障追蹤`api.example.com`。 和 請求至回應時間大於或等於五秒的服務。
```
service("api.example.com") { fault = true OR responsetime >= 5 }
```
1. 在**標籤**中，視需要編輯標籤索引鍵和值。標籤索引鍵必須是唯一的。標籤值是選用的；如果需要，您可以刪除值。若要刪除標籤，請選擇標籤列結尾的 **X**。如需標籤的詳細資訊，請參閱[標記 X-Ray 取樣規則和群組](xray-tagging.md)。
1. 選擇**建立群組**。
------
## 刪除群組
請依照本節中的步驟刪除群組。您無法刪除**預設**群組。
------
#### [ CloudWatch console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在左側導覽窗格中選擇**設定**。
1. 在 **X-Ray 追蹤**區段的**群組**下選擇**檢視設定**。
1. 從群組區段中選擇**群組**，然後選擇**刪除**。
1. 系統提示您確認時，請選擇**刪除**。
------
#### [ X-Ray console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) 開啟 X-Ray 主控台。
1. 從左側導覽窗格開啟**群組**頁面，然後選擇您要刪除的群組名稱。
1. 在**動作**功能表中，選擇**刪除群組**。
1. 當您收到確認提示時，請選擇**刪除**。
------
## 在 Amazon CloudWatch 中檢視群組指標
建立群組之後，系統會針對群組的篩選條件表達式檢查傳入的追蹤，因為這些追蹤存放在 X-Ray 服務中。符合每個條件的追蹤數量指標每分鐘都會發佈至 Amazon CloudWatch。在**編輯群組**頁面上選擇**檢視指標**會開啟 CloudWatch 主控台至**指標**頁面。如需如何使用 CloudWatch 指標的詳細資訊，請參閱《[Amazon CloudWatch 使用者指南》中的使用 Amazon CloudWatch 指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)。 *Amazon CloudWatch *
------
#### [ CloudWatch console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在左側導覽窗格中選擇**設定**。
1. 在 **X-Ray 追蹤**區段的**群組**下選擇**檢視設定**。
1. 從群組區段中選擇**群組**，然後選擇**編輯**。
1. 在**編輯群組**頁面上，選擇**檢視指標**。
CloudWatch 主控台**指標**頁面會在新標籤中開啟。
------
#### [ X-Ray console ]
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home) 開啟 X-Ray 主控台。
1. 從左側導覽窗格開啟**群組**頁面，然後選擇您要檢視指標的群組名稱。
1. 在**編輯群組**頁面上，選擇**檢視指標**。
CloudWatch 主控台**指標**頁面會在新標籤中開啟。
------
# 設定 取樣規則
您可以使用 AWS X-Ray 主控台來設定 服務的取樣規則。 AWS Distro for OpenTelemetry、X-Ray SDK 和 AWS 服務 支援具有取樣組態的[主動追蹤](xray-services.md)，使用取樣規則來決定要記錄哪些請求。
**Topics**
+ [設定 取樣規則](#xray-console-config)
+ [自訂抽樣規則](#xray-console-custom)
+ [抽樣規則選項](#xray-console-sampling-options)
+ [抽樣規則範例](#xray-console-sampling-examples)
+ [將您的服務設定為使用抽樣規則](#xray-console-sampling-service)
+ [檢視抽樣結果](#xray-console-sampling-results)
+ [後續步驟](#xray-console-sampling-nextsteps)
## 設定 取樣規則
您可以針對下列使用案例設定取樣：
+ **API Gateway Entrypoint** – API Gateway 支援取樣和主動追蹤。若要在 API 階段上啟用主動追蹤，請參閱 [的 Amazon API Gateway 主動追蹤支援 AWS X-Ray](xray-services-apigateway.md)。
+ **AWS AppSync** – AWS AppSync 支援取樣和主動追蹤。若要啟用請求的 AWS AppSync 主動追蹤，請參閱[使用 AWS X-Ray 追蹤](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html)。
+ **AWS Step Functions** – AWS Step Functions 支援取樣和主動追蹤。若要在狀態機器上 AWS Step Functions 啟用主動追蹤，請參閱 [Step Functions 中的 X-Ray 追蹤](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html)。
+ **運算平台上的 Instrument AWS Distro for OpenTelemetry ** – 使用 Amazon EC2、Amazon ECS 或 等運算平台時 AWS Elastic Beanstalk，當應用程式已使用最新的 AWS Distro for OpenTelemetry 或 X-Ray SDK 進行檢測時，支援取樣。
## 自訂抽樣規則
透過自訂抽樣規則，您可以控制記錄的資料量。您也可以修改抽樣行為，而無需修改或重新部署程式碼。取樣規則會告知 AWS Distro for OpenTelemetry (ADOT) 或 X-Ray SDK 要針對一組條件記錄多少請求。根據預設，軟體開發套件每秒會記錄第一個請求，以及任何額外請求的 5%。每秒一個請求是*儲槽*。這可確保只要服務持續提供請求，每秒都會記錄至少一個追蹤。5% 是超過儲槽大小的額外請求抽樣「速率」**。
您可以設定 X-Ray 開發套件，從程式碼隨附的 JSON 文件讀取抽樣規則。但是，當您執行服務的多個執行個體時，每個執行個體都會獨立執行抽樣。這會導致抽樣請求的整體百分比增加，因為所有執行個體的儲槽都會加在一起。此外，若要更新本機取樣規則，您必須重新部署程式碼。
透過在 X-Ray 主控台中定義抽樣規則，並將 [SDK 設定為](#xray-console-sampling-service)從 X-Ray 服務讀取規則，您可以避免這兩個問題。服務會管理每個規則的儲槽，並根據執行中的執行個體數，將配額指派給每個服務執行個體來平均分散儲槽。儲槽限制是根據您設定的規則所計算。由於規則是在 服務中設定，因此您可以管理規則，而無需進行其他部署。
**注意**
設定取樣規則時，請務必了解 X-Ray 取樣是「父系型」。這表示抽樣決策只會做出一次，通常是由處理請求的第一個X-Ray-enabled的服務 (「根」服務） 做出。
如果下游服務收到已擁有上游父項取樣決策的請求，無論其自己的任何相符取樣規則為何，都會遵守該決策。
規則套用時：您的自訂抽樣規則只會在尚未做出抽樣決策的服務上生效。這通常適用於：
應用程式的進入點 （例如 API Gateway、Load Balancer 或第一個經檢測的微服務）。
啟動全新追蹤的非同步程序或工作者。
常見缺陷：如果您為「服務 B」建立嚴格的取樣規則，但「服務 A」一律會呼叫「服務 B」，則您的服務 B 規則可能永遠不會套用，因為它只是遵循服務 A 傳遞的決定。若要變更此工作流程的追蹤取樣，您必須將取樣規則設定為根服務 （服務 A)。
**注意**
X-Ray 使用最盡力的方法套用抽樣規則，在某些情況下，有效的抽樣率可能不會完全符合設定的抽樣規則。不過，隨著時間的推移，取樣的請求數量應該接近設定的百分比。
您現在可以從 Amazon CloudWatch 主控台設定 X-Ray 抽樣規則。
**在 CloudWatch 主控台中設定抽樣規則**
1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。
1. 在**設定**下方的左側導覽窗格中選擇**設定**。
1. 選擇 **X-Ray 追蹤**區段中**取樣規則**下的**檢視設定**。
1. 若要建立規則，請選擇 **Create sampling rule (建立抽樣規則)**。
若要編輯規則，請選擇規則，然後選擇**編輯**以進行編輯。
若要刪除規則，請選擇規則，然後選擇**刪除**以刪除規則。
## 抽樣規則選項
下列選項可用於每個規則。字串值可以使用萬用字元來以符合單一字元 (`?`) 或零或多個字元 (`*`)。
**抽樣規則選項**
+ **規則名稱** （字串） – 規則的唯一名稱。
+ **優先順序** （介於 1 和 9999 之間的整數） – 取樣規則的優先順序。服務會以遞增的優先順序來評估規則，並使用符合的第一個規則來決定取樣決策。
+ **儲存器 **（非負整數） – 套用固定速率之前，每秒要檢測的比對請求固定數量。儲槽不會直接用於服務，而是集體套用至使用該規則的所有服務。
+ **速率** （介於 0 到 100 之間的整數） – 在儲槽用盡之後，與檢測相符的請求百分比。在主控台中設定取樣規則時，請選擇介於 0 到 100 之間的百分比。使用 JSON 文件在用戶端 SDK 中設定取樣規則時，請提供介於 0 和 1 之間的百分比值。
+ **服務名稱** （字串） – 檢測服務的名稱，如追蹤映射中所示。
+ X-Ray SDK – 您在記錄器上設定的服務名稱。
+ Amazon API Gateway – `api-name/stage`。
+ **服務類型** （字串） – 顯示在追蹤映射中的服務類型。對於 X-Ray 開發套件，請套用適當的外掛程式來設定服務類型：
+ `AWS::ElasticBeanstalk::Environment` – AWS Elastic Beanstalk 環境 （外掛程式）。
+ `AWS::EC2::Instance` – Amazon EC2 執行個體 （外掛程式）。
+ `AWS::ECS::Container` – Amazon ECS 容器 （外掛程式）。
+ `AWS::EKS::Container` – Amazon EKS 容器 （外掛程式）。
+ `AWS::APIGateway::Stage` – Amazon API Gateway 階段。
+ `AWS::AppSync::GraphQLAPI ` – AWS AppSync API 請求。
+ `AWS::StepFunctions::StateMachine` – AWS Step Functions 狀態機器。
+ **主機** （字串） – 來自 HTTP 主機標頭的主機名稱。
+ **HTTP 方法** （字串） – HTTP 請求的方法。
+ **URL 路徑** （字串） – 請求的 URL 路徑。
+ X-Ray SDK – HTTP 請求 URL 的路徑部分。
+ **資源 ARN** （字串） – 執行服務之 AWS 資源的 ARN。
+ X-Ray SDK – 不支援。軟體開發套件僅能使用 **Resource ARN (資源 ARN)** 設為 `*` 的規則。
+ Amazon API Gateway – 階段 ARN。
+ （選用） **屬性 **（索引鍵和值） – 取樣決策時已知的區段屬性。
+ X-Ray SDK – 不支援。軟體開發套件會忽略指定屬性的規則。
+ Amazon API Gateway – 來自原始 HTTP 請求的標頭。
+ （選用） **SamplingRateBoost** （物件） – 控制異常驅動的取樣提升行為。
+ MaxRate （介於 0 和 100 之間的整數） – 在異常期間，X-Ray 可能會增加到
+ CooldownWindowMinutes （大於 0 的整數） – 只能觸發一次提升的時段 （分鐘），防止持續提升
## 抽樣規則範例
**Example – 預設規則，沒有儲槽且速率低**
您可以修改預設規則的儲槽和速率。預設規則會套用至不符合任何其他規則的請求。
+ **儲存庫**： **0**
+ **速率**：**5**(**0.05**如果使用 JSON 文件設定）
**Example – 偵錯規則以追蹤有問題路由的所有請求**
會暫時套用高優先順序的規則來進行除錯。
+ **規則名稱**： **DEBUG – history updates**
+ **優先順序**： **1**
+ **儲存庫**： **1**
+ **速率**：**100**(**1**如果使用 JSON 文件設定）
+ **服務名稱**： **Scorekeep**
+ **Service type (服務類型)：****\$1**
+ **主機**： **\$1**
+ **HTTP 方法**： **PUT**
+ **URL 路徑**： **/history/\$1**
+ **資源 ARN**： **\$1**
**Example – POSTs的較高最低速率**
+ **規則名稱**： **POST minimum**
+ **優先順序**： **100**
+ **儲存庫**： **10**
+ **速率**：**10**(**.1**如果使用 JSON 文件設定）
+ **服務名稱**： **\$1**
+ **Service type (服務類型)：****\$1**
+ **主機**： **\$1**
+ **HTTP 方法**： **POST**
+ **URL 路徑**： **\$1**
+ **資源 ARN**： **\$1**
**Example 啟用異常驅動提升**
設定在異常期間觸發取樣提升高達 50% 的規則，冷卻時間為 10 分鐘。
+ **規則名稱**： **MyAdaptiveRule**
+ **優先順序**： **100**
+ **儲存庫**： **1**
+ **FixedRate**： **0.0510**
+ **服務名稱**： **\$1**
+ **Service type (服務類型)：****\$1**
+ **主機**： **\$1**
+ **HTTP 方法**： **POST**
+ **URL 路徑**： **\$1**
+ **maxRate**： **0.5**
+ **cooldownWindowMinutes**： **10**
## 將您的服務設定為使用抽樣規則
AWS Distro for OpenTelemetry (ADOT) 和 X-Ray SDK 需要額外的組態，才能使用您在主控台中設定的取樣規則。如需設定抽樣策略的詳細資訊，請參閱適用您語言的組態主題：
+ Java：搭配 ADOT Java [使用 X-Ray 遠端取樣](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr#using-x-ray-remote-sampling)
+ Go：使用 ADOT Go [設定取樣](https://aws-otel.github.io/docs/getting-started/go-sdk/manual-instr#configuring-sampling)
+ Node.js：搭配 ADOT JavaScript [使用 X-Ray 遠端取樣](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr#using-x-ray-remote-sampling)
+ Python：搭配 ADOT Python [使用 X-Ray 遠端取樣](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr#using-x-ray-remote-sampling)
+ Ruby： [抽樣規則](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-sampling)
+ .NET：搭配 ADOT .NET [使用 X-Ray 遠端取樣](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr#using-x-ray-remote-sampling)
如需 API Gateway，請參閱 [的 Amazon API Gateway 主動追蹤支援 AWS X-Ray](xray-services-apigateway.md)。
## 檢視抽樣結果
X-Ray 主控台**取樣**頁面顯示服務如何使用每個取樣規則的詳細資訊。
**Trend (趨勢)** 資料行會顯示過去幾分鐘內使用規則的方式。每個資料行都會顯示 10 秒間的統計資料。
**抽樣統計資料**
+ **符合的規則總數**：符合此規則的請求數量。此數量不包含本來會和此規則相符，但是卻先符合高優先順序規則的請求。
+ **取樣總數**：記錄的請求數。
+ **以固定速率取樣**：套用規則固定速率取樣的請求數。
+ **使用儲槽限制取樣**：使用 X-Ray 指派的配額取樣的請求數量。
+ **從儲槽借用**：透過從儲槽借用取樣的請求數量。服務第一次將請求符合規則時，X-Ray 尚未為其指派配額。不過，如果儲槽至少為 1，服務會借用每秒一個追蹤，直到 X-Ray 指派配額為止。
如需抽樣統計資料和服務使用抽樣規則方式的詳細資訊，請參閱[透過 X-Ray API 使用取樣規則](xray-api-sampling.md)。
## 後續步驟
您可以使用 X-Ray API 來管理抽樣規則。透過 API，您可以透過編寫程式設計的方式在排程上建立及更新規則，或是回應警示或通知。如需說明及其他規則範例，請參閱[使用 AWS X-Ray API 設定取樣、群組和加密設定](xray-api-configuration.md)。
AWS Distro for OpenTelemetry、X-Ray SDK 和 AWS 服務 也使用 X-Ray API 來讀取抽樣規則、報告抽樣結果，以及取得抽樣目標。當請求符合 X-Ray 尚未為服務指派配額的規則時，服務必須追蹤其套用每個規則的頻率、根據優先順序評估規則，以及從儲槽借用。如需服務使用 API 進行抽樣的詳細資訊，請參閱[透過 X-Ray API 使用取樣規則](xray-api-sampling.md)。
當 AWS Distro for OpenTelemetry 或 X-Ray SDK 呼叫取樣 APIs時，他們會使用 CloudWatch 代理程式做為代理。如果您已使用 TCP 連接埠 2000，您可以設定代理程式在不同連接埠上執行代理。如需詳細資訊，請參閱 [CloudWatch 代理程式安裝指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。
# 設定自適應抽樣
在異常峰值期間缺少關鍵追蹤可能會使根本原因分析變得困難。不過，維持高取樣率非常昂貴。X-Ray 自適應取樣提供對異常的完整可見性，並在正常操作期間控制成本。透過適應性取樣，您可以設定最大取樣率，而 X-Ray 會自動在該限制內調整。X-Ray 會計算擷取錯誤追蹤所需的最低提升。如果您的基準速率擷取足夠的資料，則不會發生提升。您只需在需要時支付額外的抽樣費用。
使用自適應取樣的優點：
+ 完整的事件可見性 – 在事件期間取得完整的追蹤，無需手動介入。X-Ray 會自動調整取樣率以擷取錯誤追蹤，然後返回正常速率。
+ 根本原因可見性 – 一律查看問題的來源。即使未觸發完整追蹤取樣，X-Ray 也會擷取重要的錯誤資料。
+ 最佳化成本 – 短暫取樣提升 （最多 1 分鐘） 和自動冷卻時間可防止過度取樣。您只需為診斷問題所需的資料付費。
**Topics**
+ [支援的 SDKs和平台](#adaptive-sampling-supported-sdks)
+ [選擇您的自適應抽樣方法](#adaptive-sampling-features)
+ [本機 SDK 組態](#local-sdk-configuration)
## 支援的 SDKs和平台
**支援的 SDK** – 自適應取樣需要最新版本的 ADOT 開發套件。
**支援的語言** – Java ([2.11.5](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5) 版或更新版本）
您的應用程式必須使用支援的 ADOT 開發套件進行檢測，並與 Amazon CloudWatch Agent 或 OpenTelemetry Collector 一起執行。
例如，Amazon EC2、Amazon ECS 和 Amazon EKS 是常見的平台，其中 AWS Application Signals 提供啟用 ADOT SDK 和 Amazon CloudWatch Agent 的指引。
## 選擇您的自適應抽樣方法
自適應取樣支援兩種方法：取樣提升和異常範圍擷取。這些可以獨立套用，也可以合併在一起。
### 取樣提升
自適應取樣提升是以取樣規則為基礎，並適用於現有的 X-Ray 前端型取樣模型。以前端為基礎的取樣表示在根服務進行取樣決策，而取樣旗標會在下游傳遞給呼叫鏈中的所有服務。
+ 以**規則為基礎的提升** – 提升一律與特定的 X-Ray 取樣規則繫結。每個規則都可以定義自己的最大提升速率和冷卻行為。
+ 以**頭部為基礎的抽樣** – 在根服務中做出抽樣決策，並將抽樣旗標向下游傳遞給呼叫鏈中的所有服務。
+ **異常驅動** – X-Ray 依賴 SDK 報告異常統計資料。當 X-Ray 偵測到異常，例如錯誤或高延遲時，它會使用這些統計資料來計算適當的提升速率 （高達設定的最大值）。
**異常報告**
呼叫鏈中的每個應用程式服務都可以透過所需的 SDK 發出異常統計資料：
+ **根服務** – 必須在支援的 SDK 和平台上執行，才能啟用取樣提升。如果不支援根服務，則不會進行提升。
+ **下游服務** – 下游服務只會報告異常；無法做出抽樣決策。當下游服務執行支援的 SDK 時，偵測到的異常可能會觸發取樣提升。當下游服務不受支援 （例如，執行較舊的 SDK) 時，該服務的異常不會觸發提升。當這些服務遵循標準內容傳播 （例如 W3C 追蹤內容和裝訂） 時，仍然可以在下游傳播內容。這可確保進一步下游服務中支援的 SDKs 可以報告觸發提升的異常。
**提升時間和範圍**
+ **觸發延遲** – 在 X-Ray 偵測到異常之後，您可以預期取樣提升開始的時間低至 10 秒。
+ **提升期間** – X-Ray 觸發提升後，最長會持續 1 分鐘，然後再返回基本取樣率。
+ **提升冷卻** – 提升發生後，X-Ray 不會觸發相同規則的另一個提升，直到超過冷卻時段為止。
例如，當您將 `cooldown`設定為 10 分鐘時，一旦提升結束，在接下來的 10 分鐘時段之前，就無法觸發新的提升。
特殊情況：當您將 `cooldown` 設定為 1 分鐘時，由於提升本身最多可持續 1 分鐘，因此如果異常持續存在，則可以持續有效觸發提升。
**注意**
為您的根服務使用支援的 SDKs和平台。取樣提升僅適用於支援的 SDKs和平台。雖然取樣提升有很高的機率會擷取異常追蹤，但可能不會擷取每個異常追蹤。
**提高可見性**
當取樣規則設定為調適式取樣提升時，X-Ray 會自動發出推展指標，讓您監控提升活動。
+ **指標名稱** – `SamplingRate`
+ **維度** – `RuleName`（設定為實際規則名稱）
`SamplingRateBoost` 啟用 的每個規則都會發佈其有效的取樣率，包括基準速率和任何暫時提升。這可讓您：
+ 觸發提升時的追蹤
+ 監控每個規則的有效取樣率
+ 將提升與應用程式異常 （例如錯誤峰值或延遲事件） 相關聯
您可以在 **Amazon CloudWatch Metrics 的 AWS/X-Ray 命名空間下檢視這些指標。指標值是介於 0 和 1 之間的浮點數，代表有效的取樣率**。
**使用 X-Ray 取樣規則設定取樣提升**
您可以新增`SamplingRateBoost`欄位，直接在現有的 X-Ray 取樣規則中啟用自適應取樣。如需詳細資訊，請參閱[自訂抽樣規則](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom)。這提供了一種集中式方法來啟用適應性抽樣，而無需修改應用程式程式碼或套用應用程式部署。當您啟用適應性取樣時，X-Ray 會在錯誤峰值或延遲極端值等異常期間自動增加取樣，同時將取樣率保持在設定的最大範圍內。 `SamplingRateBoost` 可以套用至取樣規則以外的任何自訂`Default`取樣規則。
`SamplingRateBoost` 欄位定義異常驅動取樣的上限和行為。
```
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
```
`MaxRate` 定義 X-Ray 在偵測到異常時將套用的最大取樣率。值範圍為 `0.0`到 `1.0`。例如， `"MaxRate": 0.25` 允許抽樣在異常時段期間增加高達 25% 的請求。X-Ray 會根據異常活動，決定基準與最大值之間的適當速率。
`CooldownWindowMinutes` 定義了只能觸發一次取樣率提升的時間範圍 （以分鐘為單位）。提升發生後，在下一個時段之前不允許進一步提升。值類型為*整數 （分鐘）*。
**具有適應性取樣的範例規則**
```
{
"RuleName": "MyAdaptiveRule",
"Priority": 1,
"ReservoirSize": 1,
"FixedRate": 0.05,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"SamplingRateBoost": {
"MaxRate": 0.25,
"CooldownWindowMinutes": 10
}
}
```
在此範例中，基準取樣為 5% (`FixedRate: 0.05`)。在異常期間，X-Ray 可以將取樣增加到 25% (`MaxRate: 0.25`)。每 10 分鐘僅提升一次。
**異常條件組態**
未提供異常條件組態時，ADOT SDK 會使用 **HTTP 5xx 錯誤代碼**作為預設異常條件來觸發取樣提升。
您也可以使用環境變數，在支援的 ADOT 開發套件中於本機微調異常情況。如需詳細資訊，請參閱[本機 SDK 組態](#local-sdk-configuration)。
### 異常範圍擷取
異常範圍擷取可確保一律記錄代表異常的關鍵範圍，即使未對完整追蹤進行取樣。此功能透過專注於擷取異常本身來補充抽樣提升，而不是增加未來追蹤的抽樣。
當 ADOT SDK 偵測到異常時，它會立即發出跨度，無論抽樣決策為何。由於 SDK 只會發出與異常相關的範圍，因此這些追蹤是部分追蹤，而不是完整的end-to-end交易。
一旦 ADOT SDK 偵測到異常跨度，它會嘗試從相同的追蹤發出盡可能多的跨度。此功能下發出的所有範圍都會以 屬性 標記`aws.trace.flag.sampled = 0`。這可讓您在交易搜尋和分析中輕鬆區分部分追蹤 （異常擷取） 與完整追蹤 （正常抽樣）。
我們建議加入[交易搜尋](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html)以檢視和查詢部分追蹤。下列範例顯示 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) 主控台中的服務頁面。ServiceC 設定為異常跨度擷取，它是套用取樣提升的呼叫鏈的一部分。此組態會產生完整和部分追蹤。您可以使用 `aws.trace.flag.sampled` 屬性來區分追蹤類型。
![\[異常範圍擷取\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/adaptive-sampling.png)
異常範圍擷取只能透過 啟用或自訂[本機 SDK 組態](#local-sdk-configuration)。
## 本機 SDK 組態
您可以透過環境變數提供 YAML 組態，在 ADOT 開發套件中設定自適應抽樣功能。本機組態提供對異常條件、閾值的精細控制。
這是*異常範圍擷取*的必要項目，以及自訂*取樣提升*條件的選用項目。以下是組態的範例：
```
version: 1.0
anomalyConditions:
- errorCodeRegex: "^5\\d\\d$"
usage: both
- operations:
- "/api"
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
usage: sampling-boost
- highLatencyMs: 1000
usage: anomaly-span-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 1
```
欄位定義如下：
+ `version` – 組態檔案的結構描述版本
+ `anomalyConditions` – 定義偵測到異常的條件及其使用方式
+ `errorCodeRegex` – 定義哪些 HTTP 狀態碼視為異常的規則表達式
+ `operations` – 套用條件的操作或端點清單
+ `highLatencyMs` – 超過範圍視為異常的延遲閾值 （以毫秒為單位）
+ `usage` – 定義條件適用的功能：
+ `both` – 適用於**取樣提升**和**異常跨度擷取 **（若未指定用量，則預設為預設值）
+ `sampling-boost` – 僅用於觸發取樣提升
+ `anomaly-span-capture` – 僅用於異常範圍擷取
+ `anomalyCaptureLimit` – 定義發出多少追蹤異常範圍的限制。
`anomalyTracesPerSecond` – 每秒擷取的異常範圍追蹤數目上限，以防止過度跨度磁碟區 （如果不存在 anomalyCaptureLimit，則預設值為 1)。
**注意**
`AnomalyConditions` **會覆寫**取樣提升的預設異常條件 (HTTP 5xx)。如果您想要在使用本機組態時保留預設條件，則必須明確地將其包含在 的任何項目中`AnomalyConditions`。
對於每個`anomalyConditions`項目：
**省略** `operations` 欄位時，條件會套用至**所有操作** （服務層級）
當 `operations` 欄位存在但設定為**空白清單**時， 條件會套用至**無操作**，使該項目成為無操作
同時省略 `errorCodeRegex`和 `highLatencyMs` 時，條件沒有要評估的異常條件，使該項目成為無操作項目
邏輯關係：
在 中的項目之間`anomalyConditions`，關係為 **OR**。
在單一項目中，多個欄位 （例如 `errorCodeRegex`和 `highLatencyMs`) 會與 **AND** 結合。
例如：
```
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300
```
此條件表示**狀態碼符合 429 或 5xx 且延遲 ≥ 300 毫秒**。
### 將本機組態套用至 ADOT SDK
您可以設定環境變數 ，將本機組態套用至 ADOT 開發套件`AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG`。值必須是有效的 YAML 文件 （內嵌或巢狀）。
例如，Amazon EC2 和 Amazon ECS，請直接設定環境變數：
```
AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}"
```
對於 Amazon EKS，請將 Pod 規格內的環境變數定義為巢狀 YAML：
```
apiVersion: v1
kind: Pod
metadata:
name: adot-sample
spec:
containers:
- name: adot-app
image: my-app:latest
env:
- name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG
value: |
version: 1.0
anomalyConditions:
- errorCodeRegex: "^500$"
usage: sampling-boost
- errorCodeRegex: "^501$"
usage: anomaly-trace-capture
anomalyCaptureLimit:
anomalyTracesPerSecond: 10
```
# 主控台深層連結
您可以使用路由和查詢來深入連結至特定追蹤，或追蹤和追蹤映射的篩選檢視。
**主控台頁面**
+ 歡迎頁面 – [xray/home\$1/welcome](https://console.aws.amazon.com/xray/home#/welcome)
+ 入門 – [xray/home\$1/getting-started](https://console.aws.amazon.com/xray/home#/getting-started)
+ 追蹤映射 – [xray/home\$1/service-map](https://console.aws.amazon.com/xray/home#/service-map)
+ 追蹤 – [xray/home\$1/traces](https://console.aws.amazon.com/xray/home#/traces)
## 追蹤
您可以為個別追蹤的時間表檢視、原始檢視及映射檢視建立連結。
**追蹤時間軸** – `xray/home#/traces/trace-id`
**原始追蹤資料** – `xray/home#/traces/trace-id/raw`
**Example – 原始追蹤資料**
```
https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw
```
## 篩選條件表達式
連結到追蹤的篩選清單。
**篩選的追蹤檢視** – `xray/home#/traces?filter=filter-expression`
**Example – 篩選條件表達式**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service("api.amazon.com") { fault = true OR responsetime > 2.5 } AND annotation.foo = "bar"
```
**Example – 篩選條件表達式 (URL 編碼）**
```
https://console.aws.amazon.com/xray/home#/traces?filter=service(%22api.amazon.com%22)%20%7B%20fault%20%3D%20true%20OR%20responsetime%20%3E%202.5%20%7D%20AND%20annotation.foo%20%3D%20%22bar%22
```
如需篩選條件表達式的詳細資訊，請參閱[使用篩選條件表達式](xray-console-filters.md)。
## 時間範圍
指定時間長度或開始及結束時間 (格式為 ISO8601)。時間範圍以 UTC 表示，最長可達 6 小時。
**時間長度** – `xray/home#/page?timeRange=range-in-minutes`
**Example – 過去一小時的追蹤映射**
```
https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H
```
**開始和結束時間** – `xray/home#/page?timeRange=start~end`
**Example – 時間範圍精確到 秒**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00:00~2023-7-01T22:00:00
```
**Example – 時間範圍精確到 分鐘**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00~2023-7-01T22:00
```
## 區域
指定 AWS 區域 以連結至該區域中的頁面。若您未指定區域，主控台會將您重新導向至最後一個前往的區域。
**區域** – `xray/home?region=region#/page`
**Example – 美國西部 （奧勒岡） 的追蹤地圖 (us-west-2)**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map
```
當您將區域與其他查詢參數一起包含時，區域查詢會在雜湊之前進行，而 X-Ray-specific查詢會在頁面名稱之後進行。
**Example – 美國西部 （奧勒岡） (us-west-2) 中最後一個小時的追蹤映射**
```
https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H
```
## 合併
**Example – 具有持續時間篩選條件的最近追蹤**
```
https://console.aws.amazon.com/xray/home#/traces?timeRange=PT15M&filter=duration%20%3E%3D%205%20AND%20duration%20%3C%3D%208
```
**輸出**
+ 頁面 – 追蹤
+ 時間範圍 – 過去 15 分鐘
+ 篩選條件 – 持續時間 >= 5 且持續時間 <= 8
# 使用 X-Ray API
如果 X-Ray SDK 不支援您的程式設計語言，您可以直接使用 X-Ray APIs或 AWS Command Line Interface (AWS CLI) 來呼叫 X-Ray API 命令。使用下列指引來選擇您與 API 的互動方式：
+ 使用 使用預先格式化的命令或 請求中的選項 AWS CLI ，來使用更簡單的語法。
+ 直接使用 X-Ray API，以針對您對 X-Ray 提出的請求，獲得最大的彈性和自訂。
如果您直接使用 [X-Ray API](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) 而非 AWS CLI，則必須以正確的資料格式來參數化請求，也可能必須設定身分驗證和錯誤處理。
下圖顯示選擇如何與 X-Ray API 互動的指引：
![\[X-Ray 會顯示應用程式請求的詳細資訊。\]](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/api-vs-cli.png)
使用 X-Ray API 將追蹤資料直接傳送到 X-Ray。X-Ray API 支援 X-Ray SDK 中提供的所有函數，包括下列常見動作：
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) – 將區段文件上傳至 X-Ray。
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) – 擷取追蹤 IDs 清單中的追蹤清單。每個擷取的追蹤都是來自單一請求的區段文件集合。
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) – 擷取追蹤IDs 和註釋。您可以指定 `FilterExpression`來擷取追蹤摘要的子集。
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html) – 擷取特定追蹤 ID 的服務圖表。
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) – 擷取JSON格式化文件，描述處理傳入請求和呼叫下游請求的服務。
您也可以使用應用程式程式碼中的 AWS Command Line Interface (AWS CLI)，以程式設計方式與 X-Ray 互動。 AWS CLI 支援 X-Ray SDK 中提供的所有函數，包括其他函數 AWS 服務。下列函數是先前以更簡單格式列出的 API 操作版本：
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html) – 將區段文件上傳至 X-Ray。
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html) – 擷取追蹤 IDs 清單中的追蹤清單。每個擷取的追蹤都是來自單一請求的區段文件集合。
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html) – 擷取追蹤IDs 和註釋。您可以指定 `FilterExpression`來擷取追蹤摘要的子集。
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html) – 擷取特定追蹤 ID 的服務圖表。
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html) – 擷取`JSON`格式化文件，描述處理傳入請求和呼叫下游請求的服務。
若要開始使用，您必須[AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)為作業系統安裝 。 AWS 支援 Linux、 macOS和 Windows 作業系統。如需 X-Ray 命令清單的詳細資訊，請參閱適用於 [AWS CLI X-Ray 的命令參考指南](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html)。
**Topics**
+ [搭配 CLI AWS 使用 AWS X-Ray API](xray-api-tutorial.md)
+ [將追蹤資料傳送至 AWS X-Ray](xray-api-sendingdata.md)
+ [從 取得資料 AWS X-Ray](xray-api-gettingdata.md)
+ [使用 AWS X-Ray API 設定取樣、群組和加密設定](xray-api-configuration.md)
+ [透過 X-Ray API 使用取樣規則](xray-api-sampling.md)
+ [AWS X-Ray 區段文件](xray-api-segmentdocuments.md)
# 搭配 CLI AWS 使用 AWS X-Ray API
CLI AWS 可讓您直接存取 X-Ray 服務，並使用 X-Ray 主控台用來擷取服務圖表和原始追蹤資料的相同 APIs。範例應用程式包含指令碼，示範如何將這些 APIs與 CLI AWS 搭配使用。
## 先決條件
此教學使用 Scorekeep 範例應用程式和隨附的指令碼，以產生追蹤資料和服務地圖。按照[入門教學](xray-gettingstarted.md)中的指示啟動應用程式。
本教學課程使用 AWS CLI 來顯示 X-Ray API 的基本使用方式。適用於 [Windows、Linux 和 OS-X 的](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) AWS CLI 提供所有人公有 APIs的命令列存取 AWS 服務。
**注意**
您必須驗證您的 AWS CLI 已設定為與 Scorekeep 範例應用程式建立所在的相同區域。
隨附的指令碼 (用來測試範例應用程式) 會使用 `cURL`，將流量傳送到 API 和 `jq` 以剖析輸出。您可以從 `jq` [stedolan.github.io](https://stedolan.github.io/jq/) 下載可執行檔，並從 下載`curl`可執行檔[https://curl.haxx.se/download.html](https://curl.haxx.se/download.html)。大多數的 Linux 和 OS X 安裝都包括 cURL。
## 產生追蹤資料
當遊戲進行中時，Web 應用程式會每隔幾秒鐘持續產生對 API 的流量，但只會產生一種類型的請求。使用 `test-api.sh` 指令碼來執行端對端案例，並在您測試 API 時產生更多元化的追蹤資料。
**使用 `test-api.sh` 指令碼**
1. 開啟 [Elastic Beanstalk 主控台](https://console.aws.amazon.com/elasticbeanstalk)。
1. 導覽至您環境的[管理主控台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)。
1. 複製頁面標頭的環境 **URL**。
1. 開啟 `bin/test-api.sh` 並將 API 的值取代為您環境的 URL。
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. 執行指令碼來產生對 API 的流量。
```
~/debugger-tutorial$ ./bin/test-api.sh
Creating users,
session,
game,
configuring game,
playing game,
ending game,
game complete.
{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
```
## 使用 X-Ray API
CLI AWS 為 X-Ray 提供的所有 API 動作提供命令，包括 [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html)和 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)。如需所使用的所有支援動作和資料類型詳細資訊，請參閱 [AWS X-Ray API 參考](https://docs.aws.amazon.com/xray/latest/api/Welcome.html)。
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
指令碼會擷取最後 10 分鐘的服務圖表。
```
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...
```
**Example bin/trace-urls.sh**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
```
指令碼會擷取前一分鐘和兩個分鐘之間產生的追蹤 URL。
```
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]
```
**Example bin/full-traces.sh**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
指令碼會擷取前一分鐘和兩個分鐘之間產生的完整追蹤。
```
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
```
## 清除
終止您的 Elastic Beanstalk 環境以關閉 Amazon EC2 執行個體、DynamoDB 資料表和其他資源。
**若要終止您的 Elastic Beanstalk 環境**
1. 開啟 [Elastic Beanstalk 主控台](https://console.aws.amazon.com/elasticbeanstalk)。
1. 導覽至您環境的[管理主控台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)。
1. 選擇**動作**。
1. 選擇 **Terminate Environment (終止環境)**。
1. 選擇**終止**。
追蹤資料會在 30 天後自動從 X-Ray 刪除。
# 將追蹤資料傳送至 AWS X-Ray
您可以將追蹤資料以區段文件的形式傳送至 X-Ray。區段文件是一種 JSON 格式字串，包含您應用程式在處理請求時執行工作的相關資訊。您的應用程式可記錄其在區段中自行執行的工作相關資料，或是在子區段中使用下游服務和資源的工作相關資料。
區段會記錄您應用程式執行工作的相關資訊。區段最少會記錄其在任務上耗費的時間、名稱及兩個 ID。追蹤 ID 會在請求於服務間傳送時追蹤請求。區段 ID 會追蹤單一服務為請求完成的工作。
**Example 最小的完成區段**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
接收到請求時，您可以傳送正在進行中的區段做為預留位置，直到完成請求。
**Example 進行中的區段**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
您可以透過 [`PutTraceSegments`](#xray-api-segments)或透過 X-Ray [協助程式直接將區段傳送至 X-Ray](#xray-api-daemon)。
大多數應用程式會使用 AWS SDK 呼叫其他 服務或存取資源。在*子區段*中記錄下游呼叫的相關資訊。X-Ray 使用子區段來識別未傳送區段的下游服務，並在服務圖表上為其建立項目。
子區段可內嵌在完整區段文件中，或是分別傳送。個別傳送子區段，以非同步追蹤長時間執行請求的下游呼叫，或避免超過區段文件大小上限 (64 kB)。
**Example 子區段**
子區段具備 `subsegment` 的 `type`，以及可識別父區段的 `parent_id`。
```
{
"name" : "www2.example.com",
"id" : "70de5b6f19ff9a0c",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979"
“end_time” : 1.478293361449E9,
“type” : “subsegment”,
“parent_id” : “70de5b6f19ff9a0b”
}
```
如需您可以包含在區段和子區段中欄位和值的詳細資訊，請參閱 [AWS X-Ray 區段文件](xray-api-segmentdocuments.md)。
**Topics**
+ [產生追蹤 ID](#xray-api-traceids)
+ [使用 PutTraceSegments](#xray-api-segments)
+ [將區段文件傳送至 X-Ray 協助程式](#xray-api-daemon)
## 產生追蹤 ID
若要將資料傳送至 X-Ray，您必須為每個請求產生唯一的追蹤 ID。
**X-Ray 追蹤 ID 格式**
X-Ray `trace_id`由以連字號分隔的三個數字組成。例如 `1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。
例如，太平洋標準時間 2016 年 12 月 1 日上午 10：00，以秒`1480615200`為單位或以十六進位數字`58406520`為單位。
+ 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字表示**。
**注意**
X-Ray 現在支援使用 OpenTelemetry 建立IDs，以及符合 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)的任何其他架構。傳送至 X-Ray 時，W3C 追蹤 ID 必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤 ID 的格式`4efaaf4d1e8720b39541901950019ee5`應該如同傳送至 X-Ray `1-4efaaf4d-1e8720b39541901950019ee5`時一樣。X-Ray IDs 包含以 Unix epoch 時間表示的原始請求時間戳記，但在以 X-Ray 格式傳送 W3C 追蹤 IDs 時不需要這樣做。
您可以撰寫指令碼來產生 X-Ray IDs 進行測試。以下是兩個範例。
**Python**
```
import time
import os
import binascii
START_TIME = time.time()
HEX=hex(int(START_TIME))[2:]
TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8'))
```
**Bash**
```
START_TIME=$(date +%s)
HEX_TIME=$(printf '%x\n' $START_TIME)
GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n')
TRACE_ID="1-$HEX_TIME-$GUID"
```
如需建立追蹤 IDs並將區段傳送至 X-Ray 協助程式的指令碼，請參閱 Scorekeep 範例應用程式。
+ Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## 使用 PutTraceSegments
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API 上傳區段文件。API 具備單一參數 (`TraceSegmentDocuments`)，會接受 JSON 區段文件清單。
使用 AWS CLI，使用 `aws xray put-trace-segments`命令將區段文件直接傳送至 X-Ray。
```
$ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}'
$ aws xray put-trace-segments --trace-segment-documents "$DOC"
{
"UnprocessedTraceSegments": []
}
```
**注意**
Windows 命令處理程式和 Windows PowerShell 針對在 JSON 字串中引述和逸出引述具有不同需求。如需詳細資訊，請參閱 AWS CLI 《 使用者指南》中的[引號字串](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings)。
輸出會列出任何處理失敗的區段。例如，若追蹤 ID 內的日期為距離現在太遠的過去日期，您可能會看到如下的錯誤。
```
{
"UnprocessedTraceSegments": [
{
"ErrorCode": "InvalidTraceId",
"Message": "Invalid segment. ErrorCode: InvalidTraceId",
"Id": "6226467e3f845502"
}
]
}
```
您可以同時傳遞多個區段文件，並以空格區隔。
```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```
## 將區段文件傳送至 X-Ray 協助程式
您可以傳送區段和子區段至 X-Ray 協助程式，而不是將區段文件傳送至 X-Ray 協助程式，這會緩衝它們並批次上傳至 X-Ray API。X-Ray SDK 會將區段文件傳送至協助程式，以避免直接呼叫 AWS 。
**注意**
如需執行精靈的說明，請參閱[在本機執行 X-Ray 協助程式](xray-daemon-local.md)。
透過 UDP 連接埠 2000 以 JSON 傳送區段，並在前面加上精靈標頭 (`{"format": "json", "version": 1}\n`)
```
{"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"}
```
在 Linux 上，您可以從 Bash 終端機將區段文件傳送到精靈。將標頭和區段文件儲存到文字檔，並使用 `cat` 將它輸送到 `/dev/udp`。
```
$ cat segment.txt > /dev/udp/127.0.0.1/2000
```
**Example segment.txt**
```
{"format": "json", "version": 1}
{"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}
```
檢查[協助程式日誌](xray-daemon.md#xray-daemon-logging)，確認已將區段傳送至 X-Ray。
```
2017-07-07T01:57:24Z [Debug] processor: sending partial batch
2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50
2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds)
```
# 從 取得資料 AWS X-Ray
AWS X-Ray 會處理您傳送給它的追蹤資料，以在 JSON 中產生完整的追蹤、追蹤摘要和服務圖表。您可以使用 CLI 直接從 API AWS 擷取產生的資料。
**Topics**
+ [擷取服務圖表](#xray-api-servicegraph)
+ [根據群組擷取服務圖表](#xray-api-servicegraphgroup)
+ [擷取追蹤](#xray-api-traces)
+ [擷取和精簡根本原因分析](#xray-api-analytics)
## 擷取服務圖表
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) API 擷取 JSON 服務圖表。API 需要開始時間及結束時間。您可以從 Linux 終端機使用 `date` 命令來計算該時間。
```
$ date +%s
1499394617
```
`date +%s` 會印出日期 (秒)。使用此數字做為結束時間，並減去時間來取得開始時間。
**Example 擷取最後 10 分鐘服務圖表的指令碼**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
下列範例顯示具有 4 個節點的服務圖表，包括用戶端節點、EC2 執行個體、DynamoDB 資料表和 Amazon SNS 主題。
**Example GetServiceGraph 輸出**
```
{
"Services": [
{
"ReferenceId": 0,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Type": "client",
"State": "unknown",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 2,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"Aliases": []
}
]
},
{
"ReferenceId": 1,
"Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA",
"Names": [
"awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA"
],
"Type": "AWS::DynamoDB::Table",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"DurationHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
]
},
{
"ReferenceId": 2,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Root": true,
"Type": "AWS::EC2::Instance",
"State": "active",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 1,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"Aliases": []
},
{
"ReferenceId": 3,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"Aliases": []
}
],
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"DurationHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
]
},
{
"ReferenceId": 3,
"Name": "SNS",
"Names": [
"SNS"
],
"Type": "AWS::SNS",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"DurationHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
]
}
]
}
```
## 根據群組擷取服務圖表
若要根據群組的內容呼叫服務圖形，請包含 `groupName` 或 `groupARN`。以下範例為服務圖表呼叫名為 Example1 的群組。
**Example 根據名稱為 Example1 群組擷取服務圖表的指令碼**
```
aws xray get-service-graph --group-name "Example1"
```
## 擷取追蹤
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 取得追蹤摘要清單。追蹤摘要包含您可以用來識別要完整下載追蹤的資訊，包含標註、請求和回應資訊，以及 ID。
呼叫 `aws xray get-trace-summaries` 時有兩個 `TimeRangeType` 標記可用：
+ **TraceId** – 預設`GetTraceSummaries`搜尋使用 TraceID 時間，並傳回在計算`[start_time, end_time)`範圍內啟動的追蹤。此時間戳記範圍是根據 TraceId 中的時間戳記編碼計算，也可以手動定義。
+ **事件時間 **– 為了在一段時間內搜尋事件， AWS X-Ray 允許使用事件時間戳記搜尋追蹤。事件時間會傳回 `[start_time, end_time)` 範圍內作用中的追蹤，無論追蹤由何時開始。
使用 `aws xray get-trace-summaries` 命令來取得追蹤摘要清單。下列命令會使用預設的 TraceId 時間，取得 1 到 2 分鐘之間的追蹤摘要清單。
**Example 取得追蹤摘要的指令碼**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example GetTraceSummaries 輸出**
```
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}
```
使用來自輸出的追蹤 ID 來透過 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API 擷取完整追蹤。
**Example BatchGetTraces 命令**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example BatchGetTraces 輸出**
```
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}
```
完整追蹤包含每個區段的文件，該文件是從所有使用相同追蹤 ID 接收到的區段文件編譯而成。這些文件不代表您的應用程式傳送到 X-Ray 的資料。而是代表 X-Ray 服務產生的已處理文件。X-Ray 會編譯應用程式傳送的區段文件，並移除不符合[區段文件結構描述的資料，以建立完整的追蹤文件](xray-api-segmentdocuments.md)。
X-Ray 也會建立*推斷區段*，以便對不會自行傳送區段的服務進行下游呼叫。例如，當您使用經檢測的用戶端呼叫 DynamoDB 時，X-Ray SDK 會記錄子區段，其中包含從其觀點來看的呼叫詳細資訊。不過，DynamoDB 不會傳送對應的區段。X-Ray 會使用子區段中的資訊來建立推斷區段，以代表追蹤映射中的 DynamoDB 資源，並將其新增至追蹤文件。
若要從 API 取得多個追蹤，您需要追蹤 IDs清單，您可以使用 `get-trace-summaries` [AWS CLI 查詢](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter)從 輸出擷取。將清單重新導向至 的輸入`batch-get-traces`，以取得特定期間內的完整追蹤。
**Example 取得一分鐘期間完整追蹤的指令碼**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
## 擷取和精簡根本原因分析
使用 [GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) 產生追蹤摘要時，可以其 JSON 格式重複使用部分追蹤摘要，以根本原因為基礎建立精簡的篩選條件表達式。如需精簡步驟的演練，請參閱以下範例。
**Example 範例 GetTraceSummaries 輸出 - 回應時間根本原因一節**
```
{
"Services": [
{
"Name": "GetWeatherData",
"Names": ["GetWeatherData"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetWeatherData",
"Coverage": 1.0,
'Remote": false
},
{
"Name": "get_temperature",
"Coverage": 0.8,
"Remote": false
}
]
},
{
"Name": "GetTemperature",
"Names": ["GetTemperature"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetTemperature",
"Coverage": 0.7,
"Remote": false
}
]
}
]
}
```
透過編輯和忽略上述輸出，可利用此 JSON 篩選條件符合根本原因的實體。針對出現在 JSON 中的每一個欄位，任何待選項目必須完全相符，否則不會傳回追蹤。已移除的欄位會成為萬用字元值，與篩選條件表達式查詢結構相容的格式。
**Example 重新格式化回應時間根本原因**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
然後，此 JSON 會透過呼叫 `rootcause.json = #[{}]`，做為篩選條件表達式的一部分使用。如需查詢篩選條件表達式的詳細資訊，請參閱[篩選條件表達式](xray-console-filters.md)一章。
**Example 範例 JSON 篩選條件**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# 使用 AWS X-Ray API 設定取樣、群組和加密設定
AWS X-Ray 提供用於設定[取樣規則](xray-console-sampling.md)、群組規則和[加密設定的](xray-console-encryption.md) APIs。
**Topics**
+ [加密設定](#xray-api-configuration-encryption)
+ [抽樣規則](#xray-api-configuration-sampling)
+ [Groups (群組)](#xray-api-configuration-groups)
## 加密設定
使用 [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)指定要用於加密的 AWS Key Management Service (AWS KMS) 金鑰。
**注意**
X-Ray 不支援非對稱 KMS 金鑰。
```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}
```
針對金鑰 ID，您可以使用別名 (如範例中所示)、金鑰 ID 或 Amazon Resource Name (ARN)。
使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) 以取得目前的組態。當 X-Ray 完成套用您的設定時，狀態會從 變更為 `UPDATING` `ACTIVE`。
```
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}
```
若要停止使用 KMS 金鑰並使用預設加密，請將加密類型設定為 `NONE`。
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## 抽樣規則
您可以使用 X-Ray API 管理帳戶中的[抽樣規則](xray-console-sampling.md)。如需新增和管理標籤的詳細資訊，請參閱 [標記 X-Ray 取樣規則和群組](xray-tagging.md)。
使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 取得所有抽樣規則。
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}
```
預設規則會套用至不符合其他規則的所有請求。這是優先順序最低的規則，且無法刪除。不過，您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) 變更速率和儲槽大小。
**Example 的 API 輸入 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) – 10000-default.json**
```
{
"SamplingRuleUpdate": {
"RuleName": "Default",
"FixedRate": 0.01,
"ReservoirSize": 0
}
}
```
以下範例使用之前的檔案做為輸入，將預設規則變更為 1%、無儲槽。標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。若要從抽樣規則中移除現有標籤，請使用 [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)
```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
```
使用 [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html) 建立額外的抽樣規則。當您建立規則時，大多數規則欄位都必須填寫。以下範例將建立兩個規則。第一個規則會設定 Scorekeep 範例應用程式的基本速率。此規則適用於所有 API 提供但不符合更高優先順序之規則的請求。
**Example 適用於 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) – 9000-base-scorekeep.json 的 API 輸入**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
第二個規則也會套用至 Scorekeep，但它的優先順序更高且更具體。此規則會設定非常低的抽樣速率以輪詢請求。這些是用戶端每隔幾秒發出的 GET 請求，以檢查遊戲狀態的變更。
**Example 適用於 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) – 5000-polling-scorekeep.json 的 API 輸入**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。
```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}
```
若要刪除抽樣規則，請使用 [https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html)。
```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
```
## Groups (群組)
您可以使用 X-Ray API 來管理帳戶中的群組。群組是由篩選條件表達式定義的追蹤集合。您可以使用 群組來產生額外的服務圖表，並提供 Amazon CloudWatch 指標。[從 取得資料 AWS X-Ray](xray-api-gettingdata.md) 如需透過 X-Ray API 使用服務圖表和指標的詳細資訊，請參閱 。如需 群組的詳細資訊，請參閱 [設定 群組](xray-console-groups.md)。如需新增和管理標籤的詳細資訊，請參閱 [標記 X-Ray 取樣規則和群組](xray-tagging.md)。
使用 `CreateGroup` 建立群組 標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。
```
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
使用 `GetGroups` 取得所有現有群組。
```
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}
```
使用 `UpdateGroup` 更新群組 標籤是選擇性的。如果您選擇新增標籤，則需要標籤索引鍵，標籤值則為選用。若要從群組中移除現有標籤，請使用 [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)。
```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
用 `DeleteGroup` 刪除群組。
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# 透過 X-Ray API 使用取樣規則
SDK AWS X-Ray 使用 X-Ray API 來取得取樣規則、報告取樣結果，以及取得配額。您可以使用這些 APIs 來進一步了解抽樣規則的運作方式，或以 X-Ray SDK 不支援的語言實作抽樣。
從使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 取得所有抽樣規則開始。
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
```
輸出會包含預設規則和自訂規則。若您尚未建立抽樣規則，請參閱[抽樣規則](xray-api-configuration.md#xray-api-configuration-sampling)。
依照遞增優先順序排序，針對傳入請求評估規則。當規則相符時，使用固定速率和儲槽大小來進行抽樣決策。記錄抽樣請求並忽略 (針對追蹤用途) 未抽樣請求。在完成抽樣決策後停止評估規則。
規則儲槽大小是在套用固定速率前，每秒要記錄的追蹤目標數。儲槽會累積套用到所有服務，因此您無法直接使用它。不過，如果不是零，您可以從儲槽借用每秒一個追蹤，直到 X-Ray 指派配額為止。在接收配額前，記錄每秒的第一個請求，然後將固定速率套用到其他請求。固定速率是介於 0 和 1.00 (100%) 間的十進位數。
以下範例會顯示對 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) 發出的呼叫，其中包含在過去 10 秒間進行的抽樣決策詳細資訊。
```
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
```
X-Ray 的回應包含要使用的配額，而不是從儲槽借用。在此範例中，服務在 10 秒間從儲槽借用 10 個追蹤，並將 10% 的固定速率套用到其他 100 個請求，其結果合計為 20 個抽樣請求。配額有效期為五分鐘 （以存留時間表示） 或直到指派新的配額為止。X-Ray 也可能指派比預設值更長的報告間隔，雖然不是在這裡。
**注意**
第一次呼叫時，來自 X-Ray 的回應可能不會包含配額。繼續從儲存借用，直到您獲得指派配額。
回應中的其他兩個欄位可能會指出輸入的問題。針對您最後一次呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 檢查 `LastRuleModification`。若其較新，請取得規則的新複本。`UnprocessedStatistics` 可包含錯誤，指出規則已遭到刪除、輸入中的統計文件過舊，或是許可錯誤。
# AWS X-Ray 區段文件
**追蹤區段**是您應用程式所處理請求的 JSON 表示。追蹤區段會記錄原始請求的相關資訊、應用程式在本機執行之工作的相關資訊，以及包含應用程式對 AWS 資源、HTTP APIs 和 SQL 資料庫進行下游呼叫相關資訊的**子區段**。
**區段文件**會將區段的相關資訊傳遞給 X-Ray。區段文件最多可達 64 kB，並包含具有子區段的整個區段、表示請求正在進行中的區段片段，或個別傳送的單一子區段。您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API 將客群文件直接傳送到 X-Ray。
X-Ray 會編譯和處理區段文件，以產生可查詢的**追蹤摘要**和**完整追蹤**，您可以分別使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)和 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) APIs 存取。除了您傳送至 X-Ray 的區段和子區段之外，服務也會使用子區段中的資訊來產生**推斷區段**，並將其新增至完整追蹤。推斷區段代表追蹤地圖中的下游服務和資源。
X-Ray 提供**區段文件的 JSON 結構描述**。您可以在此處下載結構描述：[xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip)。以下章節會更詳細的說明結構描述中所列出的欄位和物件。
區段欄位的子集由 X-Ray 編製索引，以便與篩選條件表達式搭配使用。例如，如果您將區段上的 `user` 欄位設定為唯一識別符，您可以在 X-Ray 主控台中或使用 `GetTraceSummaries` API 搜尋與特定使用者相關聯的區段。如需詳細資訊，請參閱[使用篩選條件表達式](xray-console-filters.md)。
當您使用 X-Ray 開發套件檢測應用程式時，開發套件會為您產生區段文件。SDK 不會直接將區段文件傳送到 X-Ray，而是透過本機 UDP 連接埠將文件傳輸至 [X-Ray 協助程式](xray-daemon.md)。如需詳細資訊，請參閱[將區段文件傳送至 X-Ray 協助程式](xray-api-sendingdata.md#xray-api-daemon)。
**Topics**
+ [區段欄位](#api-segmentdocuments-fields)
+ [子區段](#api-segmentdocuments-subsegments)
+ [HTTP 請求資料](#api-segmentdocuments-http)
+ [註釋](#api-segmentdocuments-annotations)
+ [中繼資料](#api-segmentdocuments-metadata)
+ [AWS 資源資料](#api-segmentdocuments-aws)
+ [錯誤和例外狀況](#api-segmentdocuments-errors)
+ [SQL 查詢](#api-segmentdocuments-sql)
## 區段欄位
區段會記錄您應用程式所處理請求的相關追蹤資訊。區段最少會記錄請求的名稱、ID、開始時間、追蹤 ID 及結束時間。
**Example 最小的完成區段**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
以下欄位為區段的必要項目或條件式必要項目。
**注意**
除非另有說明，否則值必須為字串 (最多 250 個字元)。
**必要的區段欄位**
+ `name` – 處理請求的服務邏輯名稱，最多 **200 個字元**。例如，您應用程式的名稱或網域名稱。名稱可包含 Unicode 字母、數字、空格和下列符號：`_`、`.`、`:`、`/`、`%`、`&`、`#`、`=`、`+`、`\`、`-`、`@`
+ `id` – 區段的 64 位元識別符，在相同追蹤中的區段中是唯一的，以 **16 個十六進位數字**表示。
+ `trace_id` – 唯一識別符，可連接來自單一用戶端請求的所有區段和子區段。
**X-Ray 追蹤 ID 格式**
X-Ray `trace_id`由以連字號分隔的三個數字組成。例如：`1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。
例如，10：00AM 2016 年 12 月 1 日 PST 以 epoch `58406520` 為單位是`1480615200`秒或十六進位數字。
+ 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字**表示。
**注意**
X-Ray 現在支援使用 OpenTelemetry 建立IDs，以及符合 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)的任何其他架構。W3C 追蹤 ID 在傳送至 X-Ray 時，必須以 X-Ray 追蹤 ID 格式格式化。例如，W3C 追蹤 ID 的格式`4efaaf4d1e8720b39541901950019ee5`應該如同傳送至 X-Ray `1-4efaaf4d-1e8720b39541901950019ee5`時一樣。X-Ray IDs 包含以 Unix epoch 時間表示的原始請求時間戳記，但在以 X-Ray 格式傳送 W3C 追蹤 IDs 時不需要。
**追蹤 ID 安全**
您可在[回應標頭](xray-concepts.md#xray-concepts-tracingheader)中取得追蹤 ID。使用安全的隨機演算法產生追蹤 ID，以確保攻擊者無法計算未來的追蹤 ID，並使用這些 ID 傳送請求到您的應用程式。
+ `start_time` – 區段建立時間的**數字**，以 epoch 時間的浮點秒為單位。例如 `1480615200.010` 或 `1.480615200010E9`。視需要使用任意小數位數。建議盡可能使用毫秒解析度。
+ `end_time` – 區段關閉時間的**數字**。例如 `1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` – **布林值**，設定為 ，`true`而不是指定 `end_time`來記錄區段已啟動，但未完成。應用程式收到的請求需要很長時間時，請傳送進行中區段，以追蹤請求的接收情況。回應已傳送時，請傳送完成區段以覆寫進行中的區段。針對每個請求，請只傳送一個完成區段，以及一或零個進行中區段。
**服務名稱**
區段的 `name`應與產生區段之服務的網域名稱或邏輯名稱相符。不過，這不會強制執行。具有 許可的任何應用程式[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)都可以使用任何名稱傳送客群。
以下欄位是區段的選擇性欄位。
**選擇性區段欄位**
+ `service` – 包含應用程式相關資訊的物件。
+ `version` – 識別提供請求之應用程式版本的字串。
+ `user` – 識別傳送請求之使用者的字串。
+ `origin` – 執行您應用程式 AWS 的資源類型。
**支援值**
+ `AWS::EC2::Instance` – Amazon EC2 執行個體。
+ `AWS::ECS::Container` – Amazon ECS 容器。
+ `AWS::ElasticBeanstalk::Environment` – Elastic Beanstalk 環境。
當有多個值適用您的應用程式時，請使用最具指定性的。例如，多容器 Docker Elastic Beanstalk 環境會在 Amazon ECS 容器上執行您的應用程式，而該容器又會在 Amazon EC2 執行個體上執行。在此案例中，您會將來源設為 `AWS::ElasticBeanstalk::Environment`，因為環境是其他兩個資源的父系。
+ `parent_id` – 您指定的子區段 ID，如果請求來自經檢測的應用程式。X-Ray SDK 會將父子區段 ID 新增至下游 HTTP 呼叫的[追蹤標頭](xray-concepts.md#xray-concepts-tracingheader)。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。
+ `http` – [`http`](#api-segmentdocuments-http) 物件，其中包含原始 HTTP 請求的相關資訊。
+ `aws` – [`aws`](#api-segmentdocuments-aws) 物件，其中包含應用程式提供請求之 AWS 資源的相關資訊。
+ `error`、`fault`、 `throttle`和 `cause` – 錯誤[錯誤和例外狀況](#api-segmentdocuments-errors)欄位，指出發生錯誤，並包含導致錯誤的例外狀況相關資訊。
+ `annotations` – 具有索引鍵/值對的[`annotations`](#api-segmentdocuments-annotations)物件，您希望 X-Ray 為搜尋編製索引。
+ `metadata` – [`metadata`](#api-segmentdocuments-metadata) 物件，其中包含您要存放在區段的任何其他資料。
+ `subsegments` – [`subsegment`](#api-segmentdocuments-subsegments) 物件**陣列**。
## 子區段
您可以建立子區段來記錄對 的呼叫 AWS 服務 ，以及您使用 AWS SDK 進行的資源、對內部或外部 HTTP Web APIs呼叫，或 SQL 資料庫查詢。您也可以建立子區段，除錯或標註您應用程式中的程式碼區塊。子區段可包含其他子區段，因此記錄內部函數呼叫中繼資料的自訂子區段可包含其他自訂子區段及下游呼叫的子區段。
子區段會從呼叫它的服務觀點記錄下游呼叫。X-Ray 使用子區段來識別未傳送區段的下游服務，並在服務圖表上為其建立項目。
子區段可內嵌在完整區段文件中，或是分別傳送。將子區段分別傳送，來非同步追蹤長時間執行請求的下游呼叫，或是避免超過區段文件大小上限。
**Example 具有內嵌子區段的區段**
獨立子區段具備 `subsegment` 的 `type`，以及可識別父區段的 `parent_id`。
```
{
"trace_id" : "1-5759e988-bd862e3fe1be46a994272793",
"id" : "defdfd9912dc5a56",
"start_time" : 1461096053.37518,
"end_time" : 1461096053.4042,
"name" : "www.example.com",
"http" : {
"request" : {
"url" : "https://www.example.com/health",
"method" : "GET",
"user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
"client_ip" : "11.0.3.111"
},
"response" : {
"status" : 200,
"content_length" : 86
}
},
"subsegments" : [
{
"id" : "53995c3f42cd8ad8",
"name" : "api.example.com",
"start_time" : 1461096053.37769,
"end_time" : 1461096053.40379,
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
]
}
```
對於長時間執行的請求，您可以傳送進行中區段以通知 X-Ray 已收到請求，然後單獨傳送子區段以追蹤它們，然後再完成原始請求。
**Example 進行中的區段**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example 獨立子區段**
獨立子區段具備 `subsegment` 的 `type`、`trace_id` 及 `parent_id`，可識別父區段。
```
{
"name" : "api.example.com",
"id" : "53995c3f42cd8ad8",
"start_time" : 1.478293361271E9,
"end_time" : 1.478293361449E9,
"type" : "subsegment",
"trace_id" : "1-581cf771-a006649127e371903a2de979"
"parent_id" : "defdfd9912dc5a56",
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
```
當請求完成時，透過使用 `end_time` 重新傳送它來關閉區段。完整區段會覆寫正在進行中的區段。
您也可以為觸發非同步工作流程的已完成請求分別傳送子區段。例如，web API 可能會在開始使用者請求的工作前立即傳回 `OK 200` 回應。您可以在傳送回應後立即將完整區段傳送至 X-Ray，接著再將子區段傳送至稍後完成的工作。與區段相同，您也可以傳送子區段片段來記錄子區段已啟動，然後在完成下游呼叫時使用完整的子區段覆寫它。
以下欄位為子區段的必要項目或條件式必要項目。
**注意**
除非另有說明，否則值必須為字串 (最多 250 個字元)。
**必要的子區段欄位**
+ `id` – 子區段的 64 位元識別符，在相同追蹤中的區段中是唯一的，以 **16 十六進位數字**表示。
+ `name` – 子區段的邏輯名稱。針對下游呼叫，請在呼叫資源或服務後命名子區段。針對自訂子區段，請在其檢測的程式碼 (例如函數名稱) 之後命名子區段。
+ `start_time` – 子區段建立時間的**數字**，以 epoch 時間的浮點秒為單位，精確到毫秒。例如 `1480615200.010` 或 `1.480615200010E9`。
+ `end_time` – 子區段關閉時間的**數字**。例如 `1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` – 設定為 `true`而非指定 的**布林值**`end_time`，以記錄子區段已啟動，但尚未完成。針對每個下游請求，請只傳送一個完成子區段，以及一或零個進行中子區段。
+ `trace_id` – 子區段父區段的追蹤 ID。僅在分別傳送子區段時才為必要項目。
**X-Ray 追蹤 ID 格式**
X-Ray `trace_id`由以連字號分隔的三個數字組成。例如：`1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。
例如，10：00AM 2016 年 12 月 1 日 PST 以 epoch `58406520` 為單位是`1480615200`秒或十六進位數字。
+ 追蹤的全域唯一 96 位元識別符，以 **24 十六進位數字**表示。
**注意**
X-Ray 現在支援使用 OpenTelemetry 建立IDs，以及符合 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)的任何其他架構。W3C 追蹤 ID 在傳送至 X-Ray 時，必須以 X-Ray 追蹤 ID 格式格式化。例如，W3C 追蹤 ID 的格式`4efaaf4d1e8720b39541901950019ee5`應該如同傳送至 X-Ray `1-4efaaf4d-1e8720b39541901950019ee5`時一樣。X-Ray IDs 包含以 Unix epoch 時間表示的原始請求時間戳記，但在以 X-Ray 格式傳送 W3C 追蹤 IDs 時不需要。
+ `parent_id` – 子區段父區段的區段 ID。僅在分別傳送子區段時才為必要項目。在巢狀子區段的情況下，子區段可以有一個區段或子區段作為其父項。
+ `type` – `subsegment`。 只有在單獨傳送子區段時才需要。
以下欄位是子區段的選擇性欄位。
**選擇性子區段欄位**
+ `namespace` – `aws`用於 AWS 開發套件呼叫； `remote` 用於其他下游呼叫。
+ `http` – [`http`](#api-segmentdocuments-http) 物件，其中包含傳出 HTTP 呼叫的相關資訊。
+ `aws` – [`aws`](#api-segmentdocuments-aws) 物件，其中包含您應用程式呼叫的下游 AWS 資源相關資訊。
+ `error`、`fault`、 `throttle`和 `cause` – 錯誤[錯誤和例外狀況](#api-segmentdocuments-errors)欄位，指出發生錯誤，並包含導致錯誤的例外狀況相關資訊。
+ `annotations` – 具有索引鍵/值對的[`annotations`](#api-segmentdocuments-annotations)物件，您希望 X-Ray 為搜尋編製索引。
+ `metadata` – [`metadata`](#api-segmentdocuments-metadata) 物件，其中包含您要存放在區段的任何其他資料。
+ `subsegments` – [`subsegment`](#api-segmentdocuments-subsegments) 物件**陣列**。
+ `precursor_ids` – 子區段 IDs**陣列**，可識別具有在此子區段之前完成之相同父系的子區段。
## HTTP 請求資料
使用 HTTP 區塊來記錄您應用程式所處理的 HTTP 請求相關詳細資訊 (位於區段中)，或是您應用程式對下游 HTTP API 所發出請求的相關詳細資訊 (位於子區段中)。此物件中大部分的欄位都會映射到 HTTP 請求和回應中找到的資訊。
**`http`**
所有欄位都是選擇性的。
+ `request` – 請求的相關資訊。
+ `method` – 請求方法。例如：`GET`。
+ `url` – 請求的完整 URL，從請求的通訊協定、主機名稱和路徑編譯。
+ `user_agent` – 來自請求者用戶端的使用者代理程式字串。
+ `client_ip` – 申請者的 IP 地址。可從 IP 封包的 `Source Address` 擷取，或是針對轉送的請求，則從 `X-Forwarded-For` 標頭擷取。
+ `x_forwarded_for` – （僅限區段） **布林值**，指出 `client_ip`是從 `X-Forwarded-For`標頭讀取，而且不可靠，因為它可能是偽造的。
+ `traced` – （僅限子區段） **布林值**，表示下游呼叫是對另一個追蹤服務。如果此欄位設定為 `true`，X-Ray 會將追蹤視為中斷，直到下游服務上傳的區段`parent_id`與包含此區塊之子區段`id`的 相符。
+ `response` – 回應的相關資訊。
+ `status` – **整數**，指出回應的 HTTP 狀態。
+ `content_length` – **整數**，表示回應內文的長度，以位元組為單位。
當您檢測對下游 Web api 的呼叫時，請記錄包含 HTTP 請求和回應相關資訊的子區段。X-Ray 使用 子區段來產生遠端 API 的推斷區段。
**Example 在 Amazon EC2 上執行之應用程式提供的 HTTP 呼叫區段**
```
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
**Example 下游 HTTP 呼叫的子區段**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example 下游 HTTP 呼叫的推斷區段**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
## 註釋
區段和子區段可以包含`annotations`物件，其中包含一或多個欄位，X-Ray 索引可與篩選條件表達式搭配使用。欄位可以有字串、數字或布林值 （無物件或陣列）。X-Ray 為每個追蹤編製最多 50 個註釋的索引。
**Example HTTP 呼叫區段與標註**
```
{
"id": "6b55dcc497932f1a",
"start_time": 1484789187.126,
"end_time": 1484789187.535,
"trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"annotations": {
"customer_category" : 124,
"zip_code" : 98101,
"country" : "United States",
"internal" : false
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
鍵必須為英數字元，才能使用篩選條件。允許使用底線。不允許使用其他符號和空格。
## 中繼資料
區段和子區段可以包含`metadata`物件，其中包含一或多個具有任何類型值的欄位，包括物件和陣列。只要區段文件不超過大小上限 (64 kB)，X-Ray 不會為中繼資料編製索引，且值可以是任何大小。您可以在 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API 傳回的完整區段文件中檢視中繼資料。以 開頭的欄位金鑰 (`debug`在下列範例中） `AWS.` 會保留供 提供的 SDKs AWS和用戶端使用。
**Example 使用中繼資料的自訂子區段**
```
{
"id": "0e58d2918e9038e8",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "## UserModel.saveUser",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
"subsegments": [
{
"id": "0f910026178b71eb",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 58,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
"resource_names": [
"scorekeep-user"
]
}
}
]
}
```
## AWS 資源資料
針對區段，`aws` 物件包含您應用程式於其上執行的資源相關資訊。可將多個欄位套用至單一資源。例如，在 Elastic Beanstalk 上的多容器 Docker 環境中執行的應用程式，可能具有有關 Amazon EC2 執行個體、在執行個體上執行的 Amazon ECS 容器，以及 Elastic Beanstalk 環境本身的資訊。
**`aws` (區段)**
所有欄位都是選擇性的。
+ `account_id` – 如果您的應用程式將客群傳送到不同的 AWS 帳戶，請記錄執行您應用程式的 帳戶 ID。
+ `cloudwatch_logs` – 描述單一 CloudWatch 日誌群組的物件陣列。
+ `log_group` – CloudWatch Log Group 名稱。
+ `arn` – CloudWatch Log Group ARN。
+ `ec2` – Amazon EC2 執行個體的相關資訊。
+ `instance_id` – EC2 執行個體的執行個體 ID。
+ `instance_size` – EC2 執行個體的類型。
+ `ami_id` – Amazon Machine Image ID。
+ `availability_zone` – 執行個體執行所在的可用區域。
+ `ecs` – Amazon ECS 容器的相關資訊。
+ `container` – 容器的主機名稱。
+ `container_id` – 容器的完整容器 ID。
+ `container_arn` – 容器執行個體的 ARN。
+ `eks` – Amazon EKS 叢集的相關資訊。
+ `pod` – EKS Pod 的主機名稱。
+ `cluster_name` – EKS 叢集名稱。
+ `container_id` – 容器的完整容器 ID。
+ `elastic_beanstalk` – Elastic Beanstalk 環境的相關資訊。您可以在最新 Elastic Beanstalk 平台上名為 `/var/elasticbeanstalk/xray/environment.conf`的檔案中找到此資訊。
+ `environment_name` - 環境名稱。
+ `version_label` – 目前部署到提供請求之執行個體的應用程式版本名稱。
+ `deployment_id` – **數字**，指出上次成功部署到提供請求之執行個體的 ID。
+ `xray` – 有關所用檢測類型和版本的中繼資料。
+ `auto_instrumentation` – 布林值，指出是否使用自動檢測 （例如 Java 代理程式）。
+ `sdk_version` – 正在使用的 SDK 或代理程式版本。
+ `sdk` – SDK 的類型。
**Example AWS 具有外掛程式的 區塊**
```
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
```
針對子區段，記錄應用程式存取之 AWS 服務 和資源的相關資訊。X-Ray 會使用此資訊來建立推斷區段，代表服務映射中的下游服務。
**`aws` (子區段)**
所有欄位都是選擇性的。
+ `operation` – 針對 AWS 服務 或 資源叫用的 API 動作名稱。
+ `account_id` – 如果您的應用程式存取不同帳戶中的資源，或將客群傳送至不同帳戶，請記錄擁有應用程式存取之 AWS 資源的帳戶 ID。
+ `region` – 如果資源所在的區域與您的應用程式不同，請記錄區域。例如：`us-west-2`。
+ `request_id` – 請求的唯一識別符。
+ `queue_url` – 對於 Amazon SQS 佇列上的操作，則為佇列的 URL。
+ `table_name` – 對於 DynamoDB 資料表上的操作，則為資料表的名稱。
**Example 呼叫 DynamoDB 以儲存項目的子區段**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
## 錯誤和例外狀況
當發生錯誤時，您可以記錄錯誤及其產生異常的相關詳細資訊。在您應用程式將錯誤傳回使用者時於區段中記錄錯誤，或是在下游呼叫傳回錯誤時於子區段中記錄錯誤。
**錯誤類型**
將一或多個以下欄位設為 `true` 來指出發生錯誤。若錯誤發生複合，則可套用多個類型。例如，來自下游呼叫的 `429 Too Many Requests` 錯誤可能會造成您的應用程式傳回 `500 Internal Server Error`；在這種情況下，即會套用三種類型。
+ `error` – **布林值**表示發生用戶端錯誤 （回應狀態碼為 4XX 用戶端錯誤）。
+ `throttle` – **布林值**，指出請求已調節 （回應狀態碼為 *429 太多請求*)。
+ `fault` – **布林值**表示發生伺服器錯誤 （回應狀態碼為 5XX 伺服器錯誤）。
透過在區段或子區段中包含一個**原因 (cause)** 物件來指出錯誤的原因。
**`cause`**
原因可以是 **16 字元**的異常 ID，或是具備以下欄位的物件：
+ `working_directory` – 發生例外狀況時工作目錄的完整路徑。
+ `paths` – 發生例外狀況時使用的程式庫或模組的路徑**陣列**。
+ `exceptions` – **例外**狀況物件的**陣列**。
在一或多個**異常 (exception)** 物件中包含錯誤的詳細資訊。
**`exception`**
所有欄位都是選擇性的。
+ `id` – 例外狀況的 64 位元識別符，在相同追蹤中的區段中是唯一的，以 **16 個十六進位數字**表示。
+ `message` – 例外狀況訊息。
+ `type` – 例外狀況類型。
+ `remote` – **布林值**，指出例外是由下游服務傳回的錯誤所造成。
+ `truncated` – **整數**，指出從 省略的堆疊影格數目`stack`。
+ `skipped` – **整數**，指出在此例外狀況及其子項之間略過的例外狀況數目，也就是它導致的例外狀況。
+ `cause` – 例外狀況的父系例外狀況 ID，也就是造成此例外狀況的例外狀況。
+ `stack` – **stackFrame** 物件****陣列。
若可用的話，在 **stackFrame** 物件中記錄呼叫堆疊的相關資訊。
**`stackFrame`**
所有欄位都是選擇性的。
+ `path` – 檔案的相對路徑。
+ `line` – 檔案中的行。
+ `label` – 函數或方法名稱。
## SQL 查詢
您可以建立為您應用程式對 SQL 資料庫發出的查詢建立子區段。
**`sql`**
所有欄位都是選擇性的。
+ `connection_string` – 對於不使用 URL 連線字串的 SQL Server 或其他資料庫連線，請記錄連線字串，但不包括密碼。
+ `url` – 對於使用 URL 連線字串的資料庫連線，請記錄 URL，不包括密碼。
+ `sanitized_query` – 資料庫查詢，其中任何使用者提供的值都會移除或由預留位置取代。
+ `database_type` – 資料庫引擎的名稱。
+ `database_version` – 資料庫引擎的版本編號。
+ `driver_version` – 您的應用程式使用的資料庫引擎驅動程式名稱和版本編號。
+ `user` – 資料庫使用者名稱。
+ `preparation` – `call` 如果查詢使用 `PreparedCall`；`statement`如果查詢使用 `PreparedStatement`。
**Example 使用 SQL 查詢的子區段**
```
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}
```