本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 從 X-Ray 檢測遷移至 OpenTelemetry 檢測 **注意** X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](xray-sdk-daemon-timeline.md)。 X-Ray 正在轉換為 OpenTelemetry (OTel)，作為應用程式追蹤和可觀測性的主要檢測標準。此策略轉移 AWS 符合業界最佳實務，並為客戶提供更全面、靈活且面向未來的可觀測性需求解決方案。OpenTelemetry 在業界的廣泛採用，可跨各種系統追蹤請求，包括可能未直接與 X-Ray 整合 AWS 的外部請求。 本章提供順暢轉換的建議，並強調遷移至 OpenTelemetry 型解決方案的重要性，以確保持續支援和存取應用程式檢測和可觀測性的最新功能。 建議採用 OpenTelemetry 作為檢測應用程式的可觀測性解決方案。 **Topics** + [了解 OpenTelemetry](#migration-to-opentelemetry) + [了解遷移的 OpenTelemetry 概念](#opentelemetry-concepts) + [遷移概觀](#migration-overview) + [從 X-Ray Daemon 遷移至 AWS CloudWatch 代理程式或 OpenTelemetry 收集器](#xray-Daemon-migration) + [遷移至 OpenTelemetry Java](xray-migration-opentelemetry.md) + [遷移至 OpenTelemetry Go](manual-instrumentation-go.md) + [遷移至 OpenTelemetry Node.js](migrate-xray-to-opentelemetry-nodejs.md) + [遷移至 OpenTelemetry .NET](introduction-dotnet.md) + [遷移至 OpenTelemetry Python](migrate-xray-to-opentelemetry-python.md) + [遷移至 OpenTelemetry Ruby](migrate-xray-to-opentelemetry-ruby.md) ## 了解 OpenTelemetry OpenTelemetry 是業界標準的可觀測性架構，可提供標準化通訊協定和工具來收集遙測資料。它提供統一方法來檢測、產生、收集和匯出遙測資料，例如指標、日誌和追蹤。 當您從 X-Ray SDKs遷移至 OpenTelemetry 時，可獲得下列優點： + 增強架構和程式庫檢測支援 + 支援其他程式設計語言 + 自動檢測功能 + 彈性抽樣組態選項 + 指標、日誌和追蹤的統一集合 OpenTelemetry 收集器提供比 X-Ray 協助程式更多的資料收集格式和匯出目的地選項。 ### 中的 OpenTelemetry 支援 AWS AWS 提供多種使用 OpenTelemetry 的解決方案： + AWS Distro for OpenTelemetry 將 OpenTelemetry 追蹤作為區段匯出至 X-Ray。 如需詳細資訊，請參閱 [AWS Distro for OpenTelemetry](https://aws-otel.github.io/)。 + CloudWatch Application Signals 匯出自訂 OpenTelemetry 追蹤和指標以監控應用程式運作狀態。 如需詳細資訊，請參閱[使用 Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)。 + CloudWatch OTel 端點 使用 HTTP OTel 端點搭配原生 OpenTelemetry 檢測，將 OpenTelemetry 追蹤匯出至 X-Ray。 如需詳細資訊，請參閱[使用 OTel 端點](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html)。 #### 搭配 AWS CloudWatch 使用 OpenTelemetry AWS CloudWatch 透過用戶端應用程式檢測和 native AWS CloudWatch 服務支援 OpenTelemetry 追蹤，例如 Application Signals、Trace、Map、Metrics 和 Logs。如需詳細資訊，請參閱 [OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html)。 ## 了解遷移的 OpenTelemetry 概念 下表將 X-Ray 概念映射至其 OpenTelemetry 對等項目。了解這些映射可協助您將現有的 X-Ray 檢測轉換為 OpenTelemetry： | X-Ray 概念 | OpenTelemetry 概念 | | --- | --- | | X-Ray 記錄器 | 追蹤器供應商和追蹤器 | | 服務外掛程式 | 資源偵測器 | | 區段 | （伺服器） 跨度 | | 子區段 | （非伺服器） 跨度 | | X-Ray 取樣規則 | OpenTelemetry 取樣 （可自訂） | | X-Ray 發射器 | 跨度匯出工具 （可自訂） | | 註釋/中繼資料 | 屬性 | | 程式庫檢測 | 程式庫檢測 | | X-Ray 追蹤內容 | 跨度內容 | | X-Ray 追蹤內容傳播 | W3C 追蹤內容傳播 | | X-Ray 追蹤取樣 | OpenTelemetry 追蹤取樣 | | N/A | 跨度處理 | | N/A | Baggage | | X-Ray 協助程式 | OpenTelemetry Collector | **注意** 如需 OpenTelemetry 概念的詳細資訊，請參閱 [OpenTelemetry 文件](https://opentelemetry.io/docs)。 ### 比較功能 下表顯示兩個 服務都支援哪些功能。使用此資訊來識別您在遷移期間需要解決的任何差距： | 功能 | X-Ray 檢測 | OpenTelemetry 檢測 | | --- | --- | --- | | 程式庫檢測 | 支援 | 支援 | | X-Ray 取樣 | 支援 | OTel Java/ 支援。NET/Go
ADOT Java/ 支援。NET/Python/Node.js | | X-Ray 追蹤內容傳播 | 支援 | 支援 | | 資源偵測 | 支援 | 支援 | | 區段註釋 | 支援 | 支援 | | 區段中繼資料 | 支援 | 支援 | | 零碼自動檢測 | Java 支援 | OTel Java/ 支援。NET/Python/Node.js
ADOT Java/ 支援。NET/Python/Node.js | | 手動追蹤建立 | 支援 | 支援 | ### 設定和設定追蹤 若要在 OpenTelemetry 中建立追蹤，您需要一個追蹤器。您可以透過在應用程式中初始化追蹤器*提供者來取得追蹤器*。這類似於如何使用 X-Ray 記錄器來設定 X-Ray，並在 X-Ray 追蹤中建立區段和子區段。 **注意** OpenTelemetry *Tracer 提供者*提供的組態選項比 X-Ray 記錄器更多。 #### 了解追蹤資料結構 了解基本概念和功能映射後，您可以了解特定實作詳細資訊，例如追蹤資料結構和取樣。 OpenTelemetry 使用*跨度*而非區段和子區段來建構追蹤資料。每個範圍都包含下列元件： + 名稱 + 唯一 ID + 開始和結束時間戳記 + 跨度類型 + 範圍內容 + 屬性 （索引鍵值中繼資料） + 事件 （時間戳記日誌） + 其他範圍的連結 + 狀態資訊 + 父系跨度參考 當您遷移至 OpenTelemetry 時，您的範圍會自動轉換為 X-Ray 區段或子區段。這可確保您現有的 CloudWatch 主控台體驗保持不變。 ##### 使用跨度屬性 X-Ray 開發套件提供兩種將資料新增至區段和子區段的方式： 註釋 索引用於篩選和搜尋的鍵值對 中繼資料 索引鍵/值組包含未編製索引以進行搜尋的複雜資料 根據預設，OpenTelemetry 跨度屬性會轉換為 X-Ray 原始資料中的中繼資料。若要改為將特定屬性轉換為註釋，請將其索引鍵新增至`aws.xray.annotations`屬性清單。 + 如需 OpenTelemetry 概念的詳細資訊，請參閱 [OpenTelemetry 追蹤](https://opentelemetry.io/docs/concepts/signals/traces/) + 如需 OpenTelemetry 資料如何映射到 X-Ray 資料的詳細資訊，請參閱 [OpenTelemetry 到 X-Ray 資料模型轉譯](https://aws-otel.github.io/docs/getting-started/X-Ray#otel-to-X-Ray-data-model-translation-behavior-of-aws-X-Ray-exporter) ### 偵測您環境中的資源 OpenTelemetry 使用 *Resource Detectors* 收集有關產生遙測資料之資源的中繼資料。此中繼資料會儲存為*資源屬性*。例如，產生遙測的實體可以是 Amazon ECS 叢集或 Amazon EC2 執行個體，而且可以從這些實體記錄的資源屬性可以包含 Amazon ECS 叢集 ARN 或 Amazon EC2 執行個體 ID。 + 如需支援的資源類型相關資訊，請參閱 [OpenTelemetry Resource 語意慣例](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/) + 如需有關 X-Ray 服務外掛程式的資訊，請參閱[設定 X-Ray SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-configuration.html) ### 管理抽樣策略 追蹤抽樣透過從代表性的請求子集而非所有請求收集資料，來協助您管理成本。OpenTelemetry 和 X-Ray 都支援取樣，但實作方式不同。 **注意** 取樣少於 100% 的追蹤可降低您的可觀測性成本，同時保持對應用程式效能的有意義洞察。 OpenTelemetry 提供數種內建的取樣策略，並可讓您建立自訂的取樣策略。您也可以使用某些 SDK 語言設定 X-Ray *遠端取樣器*，以搭配 OpenTelemetry 使用 X-Ray 取樣規則。 OpenTelemetry 的其他抽樣策略包括： + 父系抽樣 – 在套用其他抽樣策略之前，遵守父系的抽樣決策 + 追蹤 ID 比率型取樣 – >隨機取樣指定的跨度百分比 + 尾端取樣 – 套用取樣規則以完成 OpenTelemetry Collector 中的追蹤 + 自訂取樣器 – 使用取樣界面實作您自己的取樣邏輯 如需 X-Ray 取樣規則的資訊，請參閱 [X-Ray 主控台中的取樣規則](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html) 如需 OpenTelemetry 尾端取樣的相關資訊，請參閱[尾端取樣處理器](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor) ### 管理追蹤內容 X-Ray SDKs會管理區段內容，以正確地處理追蹤中區段和子區段之間的父子關係。OpenTelemetry 使用類似的機制來確保跨度具有正確的父系跨度。它會在整個請求內容中存放和傳播追蹤資料。例如，當您的應用程式處理請求並建立代表該請求的伺服器範圍時，OpenTelemetry 會將伺服器範圍存放在 OpenTelemetry 內容中，以便在建立子範圍時，該子範圍可以參考內容中的範圍作為其父系。 ### 傳播追蹤內容 X-Ray 和 OpenTelemetry 都使用 HTTP 標頭跨服務傳播追蹤內容。這可讓您連結不同 服務產生的追蹤資料，並維護抽樣決策。 X-Ray 開發套件會使用 X-Ray 追蹤標頭自動傳播追蹤內容。當一個服務呼叫另一個服務時，追蹤標頭包含維護追蹤之間父子關係所需的內容。 OpenTelemetry 支援多個追蹤標頭格式進行內容傳播，包括： + W3C 追蹤內容 （預設） + X-Ray 追蹤標頭 + 其他自訂格式 **注意** 您可以設定 OpenTelemetry 使用一或多個標頭格式。例如，使用 X-Ray 傳播器將追蹤內容傳送至支援 X-Ray 追蹤 AWS 的服務。 設定並使用 X-Ray 傳播器來啟用跨 AWS 服務的追蹤。這可讓您將追蹤內容傳播至 API Gateway 端點和其他支援 X-Ray 的服務。 + 如需有關 X-Ray 追蹤標頭的資訊，請參閱《X-Ray 開發人員指南》中的[追蹤標頭](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) + 如需有關 OpenTelemetry 內容傳播的資訊，請參閱 OpenTelemetry 文件中的[內容和內容傳播](https://opentelemetry.io/docs/concepts/context-propagation/) ### 使用程式庫檢測 X-Ray 和 OpenTelemetry 都提供程式庫檢測，需要最少的程式碼變更，才能將追蹤新增至您的應用程式。 X-Ray 提供程式庫檢測功能。這可讓您以最少的應用程式程式碼變更來新增預先建置的 X-Ray 檢測。這些檢測支援 AWS SDK 和 HTTP 用戶端等特定程式庫，以及 Spring Boot 或 Express.js 等 Web 架構。 OpenTelemetry 的檢測程式庫會透過程式庫掛鉤或自動程式碼修改，為您的程式庫產生詳細的跨度，而只需要最少的程式碼變更。 若要判斷 OpenTelemetry 的程式庫檢測是否支援您的程式庫，請在 OpenTelemetry 登錄檔中的 [OpenTelemetry 登錄](https://opentelemetry.io/ecosystem/registry/)檔中搜尋它。 ### 匯出追蹤 X-Ray 和 OpenTelemetry 使用不同的方法來匯出追蹤資料。 #### X-Ray 追蹤匯出 X-Ray SDKs使用發射器來傳送追蹤資料： + 將區段和子區段傳送至 X-Ray 協助程式 + 將 UDP 用於非封鎖 I/O + 依預設在 SDK 中設定 #### OpenTelemetry 追蹤匯出 OpenTelemetry 使用可設定的*跨度匯出工具*來傳送追蹤資料： + 使用 *http/protobuf* 或 *grpc* 通訊協定 + 匯出範圍至 OpenTelemetry Collector 或 CloudWatch Agent 監控的端點 + 允許自訂匯出程式組態 ### 處理和轉送追蹤 X-Ray 和 OpenTelemetry 都提供元件來接收、處理和轉送追蹤資料。 #### X-Ray 追蹤處理 X-Ray 協助程式處理追蹤處理： + 從 X-Ray SDKs接聽 UDP 流量 + 批次區段和子區段 + 將批次上傳至 X-Ray 服務 #### OpenTelemetry 追蹤處理 OpenTelemetry Collector 會處理追蹤處理： + 接收來自檢測服務的追蹤 + 處理和選擇性修改追蹤資料 + 將處理的追蹤傳送至各種後端，包括 X-Ray **注意** AWS CloudWatch Agent 也可以接收 OpenTelemetry 追蹤並將其傳送至 X-Ray。如需詳細資訊，請參閱[使用 OpenTelemetry 收集指標和追蹤](AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html)。 ### 跨度處理 (OpenTelemetry 特定概念） OpenTelemetry 使用跨處理器修改建立的跨度： + 允許在建立或完成時讀取和修改範圍 + 啟用跨度處理的自訂邏輯 ### 套件 (OpenTelemetry-soecific 概念） OpenTelemetry 的套件功能允許傳播鍵值資料： + 啟用將任意資料與追蹤內容一起傳遞 + 適用於跨服務邊界傳播應用程式特定資訊 如需 OpenTelemetry Collector 的詳細資訊，請參閱 [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) 如需有關 X-Ray 概念的資訊，請參閱[《X-Ray 開發人員指南》中的 X-Ray 概念](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html) ## 遷移概觀 本節提供遷移所需的程式碼變更概觀。以下列出特定語言指引和 X-Ray 協助程式遷移步驟。 **重要** 若要從 X-Ray 檢測完全遷移到 OpenTelemetry 檢測，您需要： 使用 OpenTelemetry 解決方案取代 X-Ray SDK 用量 將 X-Ray 協助程式取代為 CloudWatch Agent 或 OpenTelemetry Collector （使用 X-Ray Exporter) + [遷移至 OpenTelemetry Java](xray-migration-opentelemetry.md) + [遷移至 OpenTelemetry Go](manual-instrumentation-go.md) + [遷移至 OpenTelemetry Node.js](migrate-xray-to-opentelemetry-nodejs.md) + [遷移至 OpenTelemetry .NET](introduction-dotnet.md) + [遷移至 OpenTelemetry Python](migrate-xray-to-opentelemetry-python.md) + [遷移至 OpenTelemetry Ruby](migrate-xray-to-opentelemetry-ruby.md) ### 新應用程式和現有應用程式的建議 對於新的和現有的應用程式，建議使用下列解決方案在您的應用程式中啟用追蹤： 檢測 + OpenTelemetry SDKs + AWS Distro for OpenTelemetry 檢測 資料收集 + OpenTelemetry Collector + CloudWatch 代理程式 遷移至 OpenTelemetry 型解決方案後，您的 CloudWatch 體驗將保持不變。您仍然可以在 CloudWatch 主控台的追蹤和追蹤地圖頁面中檢視相同格式的追蹤，或透過 [X-Ray APIs](https://docs.aws.amazon.com/xray/latest/devguide/xray-api.html)擷取追蹤資料。 ### 追蹤設定變更 您需要將 X-Ray 設定取代為 OpenTelemetry 設定。 **X-Ray 和 OpenTelemetry 設定的比較** | 功能 | X-Ray 開發套件 | OpenTelemetry | | --- | --- | --- | | 預設組態 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/xray-sdk-migration.html) | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/xray-sdk-migration.html) | | 手動組態 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/xray-sdk-migration.html) | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/xray-sdk-migration.html) | ### 程式庫檢測變更 更新您的程式碼以使用 OpenTelemetry Library Instrumentation，而非適用於 AWS SDK、HTTP 用戶端、Web Framework 和其他程式庫的 X-Ray Library Instrumentation。這會產生 OpenTelemetry Traces，而不是 X-Ray Traces。 **注意** 程式碼變更會因語言和程式庫而異。如需詳細說明，請參閱語言特定的遷移指南。 ### Lambda 環境檢測變更 若要在 Lambda 函數中使用 OpenTelemetry，請選擇下列其中一個設定選項： 1. 使用自動檢測 Lambda Layer： + （建議） [AWS 適用於 OpenTelemetry 的 Lambda Layer](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html) **注意** 若要僅使用追蹤，請設定 Lambda 環境變數 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false`。 + [AWS 適用於 ADOT 的 受管 Lambda Layer](https://aws-otel.github.io/docs/getting-started/lambda) 1. 手動設定 Lambda 函數的 OpenTelemetry： + 使用 X-Ray UDP 範圍匯出工具設定簡易範圍處理器 + 設定 X-Ray Lambda 傳播器 ### 手動建立追蹤資料 將 X-Ray 區段和子區段取代為 OpenTelemetry 跨度： + 使用 OpenTelemetry Tracer 建立跨度 + 將屬性新增至 Spans （相當於 X-Ray 中繼資料和註釋） **重要** 傳送至 X-Ray 時： 伺服器跨度轉換為 X-Ray 區段 其他跨度轉換為 X-Ray 子區段 屬性預設會轉換為中繼資料 若要將屬性轉換為註釋，請將其索引鍵新增至`aws.xray.annotations`屬性清單。如需詳細資訊，請參閱[啟用自訂 X-Ray 註釋](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations)。 ## 從 X-Ray Daemon 遷移至 AWS CloudWatch 代理程式或 OpenTelemetry 收集器 您可以使用 CloudWatch 代理程式或 OpenTelemetry 收集器，從經檢測的應用程式接收追蹤，並將其傳送至 X-Ray。 **注意** CloudWatch 代理程式 1.300025.0 版及更新版本可以收集 OpenTelemetry 追蹤。使用 CloudWatch 代理程式而非 X-Ray 協助程式可減少您需要管理的代理程式數量。如需詳細資訊，請參閱[使用 CloudWatch 代理程式收集指標、日誌和追蹤](AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。 **Topics** + [在 Amazon EC2 或內部部署伺服器上遷移](#ec2-onprem-migration) + [在 Amazon ECS 上遷移](#ecs-migration) + [在 Elastic Beanstalk 上遷移](#beanstalk-migration) ### 在 Amazon EC2 或內部部署伺服器上遷移 **重要** 先停止 X-Ray Daemon 程序，再使用 CloudWatch 代理程式或 OpenTelemetry 收集器來防止連接埠衝突。 #### 現有的 X-Ray 協助程式設定 ##### 安裝協助程式 您使用下列其中一種方法來安裝現有的 X-Ray 協助程式用量： 手動安裝 從 X-Ray 協助程式 Amazon S3 儲存貯體下載並執行可執行檔。 自動安裝 啟動執行個體時，請使用此指令碼來安裝協助程式： ``` #!/bin/bash curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm \ -o /home/ec2-user/xray.rpm yum install -y /home/ec2-user/xray.rpm ``` ##### 設定 精靈 您現有的 X-Ray Daemon 用量已使用下列其中一種設定： + 命令列引數 + 組態檔案 (`xray-daemon.yaml`) **Example 使用組態檔** ``` ./xray -c ~/xray-daemon.yaml ``` ##### 執行精靈 您現有的 X-Ray Daemon 用量已使用下列命令啟動： ``` ~/xray-daemon$ ./xray -o -n us-east-1 ``` ##### 移除協助程式 若要從 Amazon EC2 執行個體中移除 X-Ray 協助程式： 1. 停止協助程式服務： ``` systemctl stop xray ``` 1. 刪除組態檔案： ``` rm ~/{{path}}/{{to}}/xray-daemon.yaml ``` 1. 如果已設定，請移除日誌檔案： **注意** 日誌檔案位置取決於您的組態： 命令列組態： `/var/log/xray-daemon.log` 組態檔案：檢查`LogPath`設定 #### 設定 CloudWatch 代理程式 ##### 安裝代理程式 如需安裝說明，請參閱[在內部部署伺服器上安裝 CloudWatch 代理程式](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_user-first)。 ##### 設定代理程式 1. 建立組態檔案以啟用追蹤收集。如需詳細資訊，請參閱[建立 CloudWatch 代理程式組態檔案](AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html)。 1. 設定 IAM 許可： + 連接 IAM 角色或指定代理程式的登入資料。如需詳細資訊，請參閱[設定 IAM 角色](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_permissions-first)。 + 請確定角色或登入資料包含 `xray:PutTraceSegments`許可。 ##### 啟動 代理程式 如需啟動代理程式的指示，請參閱[使用命令列啟動 CloudWatch 代理程式](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#start-CloudWatch-Agent-EC2-commands-fleet)。 #### 設定 OpenTelemetry 收集器 ##### 安裝收集器 為您的作業系統下載並安裝 OpenTelemetry 收集器。如需說明，請參閱[安裝收集器](https://opentelemetry.io/docs/collector/installation/)。 ##### 設定收集器 在收集器中設定下列元件： + awsproxy 延伸模組 X-Ray 取樣的必要項目 + OTel 接收器 從您的應用程式收集追蹤 + xray 匯出工具 將追蹤傳送至 X-Ray **Example 範例收集器組態 — otel-collector-config.yaml** ``` extensions: awsproxy: endpoint: 127.0.0.1:2000 health_check: receivers: otlp: protocols: grpc: endpoint: 127.0.0.1:4317 http: endpoint: 127.0.0.1:4318 processors: batch: exporters: awsxray: region: 'us-east-1' service: pipelines: traces: receivers: [otlp] exporters: [awsxray] extensions: [awsproxy, health_check] ``` **重要** 使用 `xray:PutTraceSegments`許可設定 AWS 登入資料。如需詳細資訊，請參閱[指定登入](sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials)資料。 ##### 啟動收集器 使用您的組態檔案執行收集器： ``` otelcol --config=otel-collector-config.yaml ``` ### 在 Amazon ECS 上遷移 **重要** 您的任務角色必須擁有您使用的任何收集器的 `xray:PutTraceSegments` 許可。 在相同主機上執行 CloudWatch 代理程式或 OpenTelemetry 收集器容器之前，請先停止任何現有的 X-Ray 協助程式容器，以防止連接埠衝突。 #### 使用 CloudWatch 代理程式 1. 從 [Amazon ECR Public Gallery](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent) 取得 Docker 映像。 1. 建立名為 的組態檔案`cw-agent-otel.json`： ``` { "traces": { "traces_collected": { "xray": { "tcp_proxy": { "bind_address": "0.0.0.0:2000" } }, "otlp": { "grpc_endpoint": "0.0.0.0:4317", "http_endpoint": "0.0.0.0:4318" } } } } ``` 1. 將組態存放在 Systems Manager 參數存放區： 1. 開啟 https：//[https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) 1. 選擇**建立參數** 1. 輸入下列值： + 名稱：`/ecs/cwagent/otel-config` + 層：標準 + 類型：字串 + 資料類型：文字 + 值：【在此貼上 cw-agent-otel.json 組態】 1. 使用橋接網路模式建立任務定義： 在您的任務定義中，組態取決於您使用的聯網模式。預設值是橋接聯網，可在您的預設 VPC 中使用。在橋接網路中，設定 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`環境變數，以告知 OpenTelemetry SDK CloudWatch 代理程式的端點和連接埠。您也應該建立從應用程式容器到收集器容器的連結，以便從應用程式中的 OpenTelemetry SDK 將追蹤傳送至收集器容器。 **Example CloudWatch 代理程式任務定義** ``` { "containerDefinitions": [ { "name": "cwagent", "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest", "portMappings": [ { "containerPort": 4318, "hostPort": 4318, "protocol": "tcp" }, { "containerPort": 4317, "hostPort": 4317, "protocol": "tcp" }, { "containerPort": 2000, "hostPort": 2000, "protocol": "tcp" } ], "secrets": [ { "name": "CW_CONFIG_CONTENT", "valueFrom": "/ecs/cwagent/otel-config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["cwagent"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://cwagent:4318/v1/traces" } ] } ] } ``` 如需詳細資訊，請參閱[部署 CloudWatch 代理程式以在 Amazon ECS 上收集 Amazon EC2 執行個體層級指標](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/deploy-container-insights-ECS-instancelevel.html)。 #### 使用 OpenTelemetry 收集器 1. `otel/opentelemetry-collector-contrib` 從 Docker [Hub 取得 Docker](https://hub.docker.com/r/otel/opentelemetry-collector-contrib) 映像。 1. `otel-collector-config.yaml` 使用 **Amazon EC2 設定收集器**區段中所示的相同內容建立名為 的組態檔案，但更新端點以使用 `0.0.0.0`而非 `127.0.0.1`。 1. 若要在 Amazon ECS 中使用此組態，您可以將組態存放在 Systems Manager 參數存放區中。首先，前往 Systems Manager 參數存放區主控台，然後選擇**建立新參數 **。使用下列資訊建立新的參數： + 名稱：/ecs/otel/config （此名稱將在收集器的任務定義中參考） + 層：標準 + 類型：字串 + 資料類型：文字 + 值：【在此貼上 otel-collector-config.yaml 組態】 1. 建立任務定義，以使用橋接網路模式做為範例來部署 OpenTelemetry 收集器。 在任務定義中，組態取決於您使用的聯網模式。預設值是橋接聯網，可在您的預設 VPC 中使用。在橋接網路中，設定 `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`環境變數，以告知 OpenTelemetry SDK OpenTelemetry Collector 的端點和連接埠。您也應該建立從應用程式容器到收集器容器的連結，以便從應用程式中的 OpenTelemetry SDK 將追蹤傳送至收集器容器。 **Example OpenTelemetry 收集器任務定義** ``` { "containerDefinitions": [ { "name": "otel-collector", "image": "otel/opentelemetry-collector-contrib", "portMappings": [ { "containerPort": 2000, "hostPort": 2000 }, { "containerPort": 4317, "hostPort": 4317 }, { "containerPort": 4318, "hostPort": 4318 } ], "command": [ "--config", "env:SSM_CONFIG" ], "secrets": [ { "name": "SSM_CONFIG", "valueFrom": "/ecs/otel/config" } ] }, { "name": "application", "image": "APPLICATION_IMAGE", "links": ["otel-collector"], "environment": [ { "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT", "value": "http://otel-collector:4318/v1/traces" } ] } ] } ``` ### 在 Elastic Beanstalk 上遷移 **重要** 使用 CloudWatch 代理程式來防止連接埠衝突之前，請先停止 X-Ray Daemon 程序。 您現有的 X-Ray 協助程式整合已使用 Elastic Beanstalk 主控台開啟，或使用組態檔案在應用程式原始程式碼中設定 X-Ray 協助程式。 #### 使用 CloudWatch 代理程式 在 Amazon Linux 2 平台上，使用`.ebextensions`組態檔案設定 CloudWatch 代理程式： 1. 在專案根目錄中建立名為 `.ebextensions`的目錄 1. 使用下列內容`cloudwatch.config`在 `.ebextensions`目錄中建立名為 的檔案： ``` files: "/opt/aws/amazon-cloudwatch-agent/etc/config.json": mode: "0644" owner: root group: root content: | { "traces": { "traces_collected": { "otlp": { "grpc_endpoint": "12.0.0.1:4317", "http_endpoint": "12.0.0.1:4318" } } } } container_commands: start_agent: command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/config.json -s ``` 1. 部署時，請在應用程式原始碼套件中包含 `.ebextensions`目錄 如需 Elastic Beanstalk 組態檔案的詳細資訊，請參閱[使用組態檔案進行進階環境自訂](elasticbeanstalk/latest/dg/ebextensions.html)。