本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 檢測您的應用程式 AWS X-Ray
<a name="xray-instrumenting-your-app"></a>

**注意**  
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 SDK、Apache HTTP 用戶端或 SQL 用戶端。
+ *手動檢測* – 在您要傳送追蹤資訊的每個位置，將檢測程式碼新增至您的應用程式。

 有數個 SDKs、代理程式和工具可用於檢測您的應用程式以進行 X-Ray 追蹤。

**Topics**
+ [使用 AWS Distro for OpenTelemetry 檢測您的應用程式](#xray-instrumenting-opentel)
+ [使用 AWS X-Ray SDKs 檢測您的應用程式](#xray-instrumenting-xray-sdk)
+ [選擇 AWS Distro for OpenTelemetry 和 X-Ray SDKs](#xray-instrumenting-choosing)

## 使用 AWS Distro for OpenTelemetry 檢測您的應用程式
<a name="xray-instrumenting-opentel"></a>

 AWS Distro for OpenTelemetry (ADOT) 是以雲端原生運算基金會 (CNCF) OpenTelemetry 專案為基礎的 AWS 分佈。OpenTelemetry 提供一組單一開放原始碼 APIs、程式庫和代理程式，以收集分散式追蹤和指標。此工具組是上游 OpenTelemetry 元件的分佈，包括 SDKs、自動檢測代理程式和由 測試、最佳化、保護和支援的收集器 AWS。

透過 ADOT，工程師可以一次檢測其應用程式，並將相關指標和追蹤傳送至多個 AWS 監控解決方案 AWS X-Ray，包括 Amazon CloudWatch 和 Amazon OpenSearch Service。

將 X-Ray 與 ADOT 搭配使用需要兩個元件：啟用與 X-Ray 搭配使用的 *OpenTelemetry SDK*，以及啟用與 X-Ray 搭配使用的 *AWS Distro for OpenTelemetry Collector*。如需搭配 AWS AWS X-Ray 和其他 使用 Distro for OpenTelemetry 的詳細資訊 AWS 服務，請參閱 [AWS Distro for OpenTelemetry 文件](https://aws-otel.github.io/docs/introduction)。

如需語言支援和用量的詳細資訊，請參閱 [AWS GitHub 上的可觀測性](https://github.com/aws-observability)。

**注意**  
您現在可以使用 CloudWatch 代理程式從 Amazon EC2 執行個體和內部部署伺服器收集指標、日誌和追蹤。CloudWatch 代理程式 1.300025.0 版及更新版本可以從 [OpenTelemetry](#xray-instrumenting-opentel) 或 [X-Ray](#xray-instrumenting-xray-sdk) 用戶端 SDKs 收集追蹤，並將其傳送至 X-Ray。使用 CloudWatch 代理程式而非 AWS Distro for OpenTelemetry (ADOT) 收集器或 X-Ray 協助程式來收集追蹤，可協助您減少管理的代理程式數量。如需詳細資訊，請參閱 [CloudWatch 使用者指南中的 CloudWatch 代理程式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)主題。 CloudWatch 

ADOT 包括下列項目：
+ [AWS Distro for OpenTelemetry Go](https://aws-otel.github.io/docs/getting-started/go-sdk)
+ [AWS Distro for OpenTelemetry Java](https://aws-otel.github.io/docs/getting-started/java-sdk)
+ [AWS Distro for OpenTelemetry JavaScript](https://aws-otel.github.io/docs/getting-started/javascript-sdk)
+ [AWS Distro for OpenTelemetry Python](https://aws-otel.github.io/docs/getting-started/python-sdk)
+ [AWS Distro for OpenTelemetry .NET](https://aws-otel.github.io/docs/getting-started/dotnet-sdk)

ADOT 目前包含 [Java](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr) 和 [Python](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr) 的自動檢測支援。此外，ADOT 可透過 ADOT Managed AWS Lambda Layers，使用 Java、Node.js 和 Python 執行時間自動檢測 Lambda 函數及其下游請求。 [https://aws-otel.github.io/docs/getting-started/lambda](https://aws-otel.github.io/docs/getting-started/lambda)

適用於 Java 和 Go SDKs支援 X-Ray 集中式抽樣規則。如果您需要支援其他語言的 X-Ray 抽樣規則，請考慮使用 AWS X-Ray SDK。

**注意**  
您現在可以傳送 W3C IDs 至 X-Ray。根據預設，使用 OpenTelemetry 建立的追蹤具有以 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)為基礎的追蹤 ID 格式。這與使用 X-Ray 開發套件或整合 X-Ray AWS 的服務建立IDs 格式不同。若要確保 X-Ray 接受 W3C 格式IDs，您必須使用 [AWS X-Ray Exporter](https://aws-otel.github.io/docs/getting-started/x-ray) 版本 0.86.0 或更新版本，其中包含 [ADOT Collector](https://aws-otel.github.io/download) 版本 0.34.0 和更新版本。舊版匯出工具會驗證追蹤 ID 時間戳記，這可能會導致 W3C IDs 遭到拒絕。

## 使用 AWS X-Ray SDKs 檢測您的應用程式
<a name="xray-instrumenting-xray-sdk"></a>

 AWS X-Ray 包含一組語言特定的 SDKs用於檢測您的應用程式，以將追蹤傳送至 X-Ray。每個 X-Ray 開發套件都提供下列項目：
+ *攔截程式*，可新增至您的程式碼以追蹤傳入的 HTTP 請求
+ *用戶端處理常式*可檢測您的應用程式用來呼叫其他 的 AWS SDK 用戶端 AWS 服務
+ 用來檢測對其他內部和外部 HTTP Web *服務的呼叫的 HTTP 用戶端* 

X-Ray SDKs也支援檢測對 SQL 資料庫的呼叫、自動 AWS SDK 用戶端檢測和其他功能。開發套件不會將追蹤資料直接傳送到 X-Ray，而是將 JSON 區段文件傳送到監聽 UDP 流量的協助程式程序。[X-Ray 協助程式](xray-daemon.md)會緩衝佇列中的區段，並分批上傳至 X-Ray。

提供下列特定語言SDKs：
+ [AWS X-Ray 適用於 Go 的 SDK](xray-sdk-go.md)
+ [AWS X-Ray 適用於 Java 的開發套件](xray-sdk-java.md)
+ [AWS X-Ray 適用於 Node.js 的 SDK](xray-sdk-nodejs.md)
+ [AWS X-Ray 適用於 Python 的 SDK](xray-sdk-python.md)
+ [AWS X-Ray 適用於 .NET 的 SDK](xray-sdk-dotnet.md)
+ [AWS X-Ray 適用於 Ruby 的 SDK](xray-sdk-ruby.md)

X-Ray 目前包含 [Java](aws-x-ray-auto-instrumentation-agent-for-java.md) 的自動檢測支援。

## 選擇 AWS Distro for OpenTelemetry 和 X-Ray SDKs
<a name="xray-instrumenting-choosing"></a>

 X-Ray 隨附的SDKs是 提供的緊密整合檢測解決方案的一部分 AWS。 AWS Distro for OpenTelemetry 是更廣泛的產業解決方案的一部分，其中 X-Ray 只是許多追蹤解決方案之一。您可以使用任一方法在 X-Ray 中實作end-to-end追蹤，但請務必了解差異，以判斷對您最有用的方法。

 如果您需要下列項目，建議您使用 AWS Distro for OpenTelemetry 檢測應用程式：
+ 無需重新檢測程式碼，即可將追蹤傳送至多個不同的追蹤後端
+ 支援各種語言的大量程式庫檢測，由 OpenTelemetry 社群維護
+ 完全受管的 Lambda 層，可封裝收集遙測資料所需的一切，而無需在使用 Java、Python 或 Node.js 時變更程式碼
**注意**  
AWS Distro for OpenTelemetry 提供更簡單的 Lambda 函數檢測入門體驗。不過，由於 OpenTelemetry 提供的靈活性，您的 Lambda 函數將需要額外的記憶體，並且調用可能會遇到冷啟動延遲增加，這可能會導致額外的費用。如果您要最佳化低延遲，而且不需要 OpenTelemetry 的進階功能，例如可動態設定的後端目的地，建議您使用 AWS X-Ray 開發套件來檢測應用程式。

 如果您需要下列項目，建議您選擇 X-Ray 開發套件來檢測您的應用程式：
+ 緊密整合的單一供應商解決方案
+ 與 X-Ray 集中式抽樣規則整合，包括能夠從 X-Ray 主控台設定抽樣規則，並在使用 Node.js、Python、Ruby 或 .NET 時自動跨多個主機使用它們