本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 从 X-Ray 仪器迁移到 OpenTelemetry 仪器 **注意** X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， Amazon X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 Amazon 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。 X-Ray 正在过渡到 OpenTelemetry (OTel) 作为其应用跟踪和可观察性的主要仪器标准。这种战略转变 Amazon 符合行业最佳实践，为客户提供了更全面、更灵活和面向未来的解决方案，以满足他们的可观察性需求。 OpenTelemetry它在业界得到广泛采用，可以跨不同的系统追踪请求，包括 Amazon 那些可能无法直接与 X-Ray 集成的外部系统。 本章为平稳过渡提供了建议，并强调了迁移到 OpenTelemetry基于解决方案的重要性，以确保持续支持和访问应用程序仪器和可观察性方面的最新功能。 建议将其 OpenTelemetry 用作用于检测应用程序的可观察性解决方案。 **Topics** + [理解 OpenTelemetry](#migration-to-opentelemetry) + [了解迁移 OpenTelemetry 概念](#opentelemetry-concepts) + [迁移概述](#migration-overview) + [从 X-Ray Daemon 迁移到 Amazon 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，您将获得以下好处： + 增强的框架和库检测支持 + 对其他编程语言的支持 + 自动检测功能 + 灵活的采样配置选项 + 统一收集指标、日志和跟踪数据的方法 与 X-Ray 守护程序相比，收集 OpenTelemetry 器为数据收集格式和导出目标提供了更多的选项。 ### OpenTelemetry 支持 Amazon Amazon 为处理以下问题提供了多种解决方案 OpenTelemetry： + Amazon 发行版适用于 OpenTelemetry 将 OpenTelemetry 轨迹作为分段导出到 X-Ray。 有关更多信息，请参阅[Amazon 发行版。 OpenTelemetry](https://aws-otel.github.io/) + CloudWatch 应用程序信号 导出自定义 OpenTelemetry 跟踪和指标以监控应用程序运行状况。 有关更多信息，请参阅[使用 Application Signals](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)。 + CloudWatch OTel 端点 使用带有本机 OpenTelemetry 仪器的 HTTP OTel 端点将 OpenTelemetry 跟踪导出到 X-Ray。 有关更多信息，请参阅[使用 OTel 终端节点](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html)。 #### OpenTelemetry 与一起使用 Amazon CloudWatch Amazon CloudWatch 支持 OpenTelemetry 通过客户端应用程序工具和本机 Amazon CloudWatch 服务（例如应用程序信号、跟踪、地图、指标和日志）进行跟踪。有关更多信息，请参阅 [OpenTelemetry](https://docs.amazonaws.cn/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 轨迹采样 | | 不适用 | 跨度处理 | | 不适用 | Baggage | | X-Ray 进程守护程序 | OpenTelemetry 收藏家 | **注意** 有关 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 跟踪中创建分段和子分段的方式类似。 **注意** 与 X-Ray Record OpenTelemetry *er 相比，Tracer Provider* 提供了更多的配置选项。 #### 了解跟踪数据结构 在了解了基本概念和功能映射关系之后，您可以了解特定的实现细节，例如跟踪数据结构和采样。 OpenTelemetry 使用*跨度*而不是分段和子分段来构造跟踪数据。每个跨度都包含以下组件： + Name + 唯一 ID + 开始和结束时间戳 + 跨度类型 + 跨度上下文 + 属性（键值元数据） + 事件（带时间戳的日志） + 指向其他跨度的链接 + 状态信息 + 父跨度引用 迁移到时 OpenTelemetry，您的跨度会自动转换为 X-Ray 分段或子分段。这样可以确保您现有的主 CloudWatch 机体验保持不变。 ##### 使用跨度属性 X-Ray SDK 提供了两种向分段和子分段添加数据的方法： Annotations 为了筛选和搜索而编制索引的键值对 元数据 包含未为了搜索而编制索引的复杂数据的键值对 默认情况下， 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 使用*资源检测器*收集有关生成遥测数据的资源的元数据。此元数据以*资源属性*的形式存储。例如，生成遥测数据的实体可以是 Amazon ECS 集群或 Amazon EC2 实例，而可从这些实体记录的资源属性包括 Amazon ECS 集群 ARN 或 Amazon EC2 实例 ID。 + 有关支持的资源类型的信息，请参阅[OpenTelemetry 资源语义](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/)约定 + 有关 X-Ray 服务插件的信息，请参阅[配置 X-Ray SDK](https://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-python-configuration.html)。 ### 管理采样策略 跟踪采样通过从具有代表性的请求子集而不是所有请求中收集数据，帮助您管理成本。 OpenTelemetry 和 X-Ray 都支持采样，但实现方式有所不同。 **注意** 采样少于 100% 的跟踪可以降低可观测性成本，同时提供对应用程序性能的有意义见解。 OpenTelemetry 提供了多种内置采样策略，并允许您创建自定义采样策略。您还可以使用某些 SDK 语言配置 X-*Remote Sampler*，以便使用 X-Ray 采样规则。 OpenTelemetry 来自的其他抽样策略 OpenTelemetry 有： + 基于父跨度的采样 – 在应用其他采样策略之前，请遵循父跨度采样决策 + 基于跟踪 ID 比率的采样 – >随机采样指定百分比的跨度 + 尾部采样 — 将采样规则应用于 OpenTelemetry 收集器中的完整轨迹 + 自定义采样器 – 利用采样接口实施自己的采样逻辑 有关 X-Ray 采样规则的信息，请参阅 [X-Ray 控制台中的采样规则](https://docs.amazonaws.cn/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 和 HTTP 标头都 OpenTelemetry 使用 HTTP 标头跨服务传播跟踪上下文。这使您可以链接不同服务生成的跟踪数据并维护采样决策。 X-Ray SDK 使用 X-Ray 跟踪标头自动传播跟踪上下文。当一个服务调用另一个服务时，跟踪标头包含维护跟踪之间父子关系所需的上下文。 OpenTelemetry 支持用于上下文传播的多种跟踪标头格式，包括： + W3C 跟踪上下文（默认） + X-Ray 跟踪标头 + 其他自定义格式 **注意** 您可以配置 OpenTelemetry 为使用一种或多种标题格式。例如，使用 X-Ray Propagator 向支持 X-Ray 跟踪的 Amazon 服务发送跟踪上下文。 配置并使用 X-Ray Propagator 启用跨 Amazon 服务的跟踪。这让您可以将跟踪上下文传播到 API Gateway 端点和其他支持 X-Ray 的服务。 + 有关 X-Ray 跟踪标头的信息，请参阅《X-Ray 开发人员指南》中的[跟踪标头](https://docs.amazonaws.cn/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader) + 有关 OpenTelemetry 上下文传播的信息，请参阅 OpenTelemetry 文档中的[上下文和上下文传播](https://opentelemetry.io/docs/concepts/context-propagation/) ### 使用库检测 X-Ray 和 X-Ray 都 OpenTelemetry 提供了库工具，只需最少的代码更改即可向应用程序添加跟踪。 X-Ray 提供了多项库检测功能。这让您能够在几乎不修改应用程序代码的情况下添加预构建的 X-Ray 检测功能。这些工具支持特定的库，例如 Amazon SDK 和 HTTP 客户端，以及 Spring Boot 或 Express.js 等网络框架。 OpenTelemetry的工具库通过库挂钩或自动代码修改为您的库生成详细的跨度，只需最少的代码更改。 [要确定 OpenTelemetry's Library Instrumentations是否支持您的库，请在 OpenTelemetry 注册表的注册表中进行搜索。OpenTelemetry ](https://opentelemetry.io/ecosystem/registry/) ### 导出跟踪数据 X-Ray 并 OpenTelemetry 使用不同的方法导出跟踪数据。 #### X-Ray 跟踪导出 X-Ray SDKs 使用发射器发送轨迹数据： + 将分段和子分段发送到 X-Ray 进程守护程序 + 使用 UDP 实现非阻塞 I/O + 在 SDK 中默认配置 #### OpenTelemetry 追踪导出 OpenTelemetry 使用可配置的 *Span* 导出器发送跟踪数据： + 使用 *http/protobuf* 或 *grpc* 协议 + 将跨度导出到由 OpenTelemetry 收集器或 CloudWatch 代理监控的端点 + 支持自定义导出程序配置 ### 处理和转发跟踪数据 X-Ray 和都 OpenTelemetry 提供用于接收、处理和转发跟踪数据的组件。 #### X-Ray 跟踪处理 X-Ray 进程守护程序负责跟踪处理： + 监听来自 X-Ray 的 UDP 流量 SDKs + 批处理分段和子分段 + 将各批次上传到 X-Ray 服务 #### OpenTelemetry 跟踪处理 OpenTelemetry 收集器负责跟踪处理： + 接收来自已检测服务的跟踪数据 + 处理并修改（可选）跟踪数据 + 将处理过的跟踪数据发送到各种后端，包括 X-Ray **注意** Amazon CloudWatch 代理还可以接收 OpenTelemetry 跟踪并将其发送到 X-Ray。有关更多信息，请参阅使用[收集指标和跟踪 OpenTelemetry](AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html)。 ### 跨度处理（OpenTelemetry特定概念） OpenTelemetry 使用跨度处理器在创建跨度时对其进行修改： + 支持在创建或完成时读取和修改跨度 + 启用跨度处理的自定义逻辑 ### 行李（OpenTelemetry特定概念） OpenTelemetry的行李功能允许传播键值数据： + 支持在跟踪上下文旁边传递任意数据 + 对于跨服务边界传播应用程序特定的信息很有用 有关 OpenTelemetry 收集器的信息，请参见[OpenTelemetry 收集器](https://opentelemetry.io/docs/collector/) 有关 X-Ray 概念的信息，请参阅《X-Ray 开发人员指南》中的 [X-Ray 概念](https://docs.amazonaws.cn/xray/latest/devguide/xray-concepts.html) ## 迁移概述 本节概述了迁移所需的代码更改。以下是针对不同语言的具体指导以及 X-Ray 进程守护程序的迁移步骤。 **重要** 要从 X-Ray 仪器完全迁移到 OpenTelemetry 仪器，您需要： 用 OpenTelemetry 解决方案取代 X-Ray SDK 的使用 将 X-Ray 守护程序替换为 CloudWatch 代理或 OpenTelemetry 收集器（使用 X-Ray 导出器） + [迁移到 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) ### 针对新的和现有的应用程序的建议 对于新的和现有的应用程序，建议使用以下解决方案在应用程序中启用跟踪： Instrumentation + OpenTelemetry SDKs + Amazon 仪器仪表发行 OpenTelemetry 版 数据收集 + OpenTelemetry 收藏家 + CloudWatch 代理人 迁移到 OpenTelemetry基于基础的解决方案后，您的 CloudWatch 体验将保持不变。您仍然可以在 CloudWatch 控制台的 Traces 和 Trace Map 页面中以相同格式查看您的踪迹，或者通过 [X-](https://docs.amazonaws.cn/xray/latest/devguide/xray-api.html) Ray 检索您的跟踪数据 APIs。 ### 跟踪设置更改 您需要用设置替换 X-Ray OpenTelemetry 设置。 **X-Ray 和 OpenTelemetry 设置的比较** | 功能 | X-Ray SDK | OpenTelemetry | | --- | --- | --- | | 默认配置 | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html) | | 手动配置 | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/xray/latest/devguide/xray-sdk-migration.html) | ### 库检测更改 更新您的代码，使用 OpenTelemetry 库工具代替 Amazon SDK、HTTP 客户端、Web 框架和其他库的 X-Ray 库工具。这会生成 OpenTelemetry 轨迹而不是 X-Ray 轨迹。 **注意** 代码更改因语言和库而异。有关详细说明，请参阅语言特定的迁移指南。 ### Lambda 环境检测更改 要 OpenTelemetry 在 Lambda 函数中使用，请选择以下设置选项之一： 1. 使用自动检测 Lambda 层： + （推荐）适用于 [Amazon Lambda 层 OpenTelemetry](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html) **注意** 要仅使用跟踪，请设置 Lambda 环境变量 `OTEL_Amazon_APPLICATION_SIGNALS_ENABLED=false`。 + [Amazon 适用于 ADOT 的托管 Lambda 层](https://aws-otel.github.io/docs/getting-started/lambda) 1. 手动设置您 OpenTelemetry 的 Lambda 函数： + 使用 X-Ray UDP 跨度导出程序配置简单跨度处理器 + 设置 X-Ray Lambda 传播器 ### 手动创建跟踪数据 将 X-Ray 分段和子分段替换为 OpenTelemetry Span： + 使用示 OpenTelemetry 踪剂创建跨度 + 向跨度添加属性（等同于 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 迁移到 Amazon CloudWatch 代理或收集器 OpenTelemetry 您可以使用 CloudWatch 代理或 OpenTelemetry 采集器从装有仪器的应用程序接收跟踪并将其发送到 X-Ray。 **注意** CloudWatch 代理版本 1.300025.0 及更高版本可以收集跟踪。 OpenTelemetry 使用 CloudWatch 代理代替 X-Ray Daemon 可以减少需要管理的代理数量。有关更多信息，请参阅使用[ CloudWatch 代理收集指标、日志和跟踪](AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。 **Topics** + [在 Amazon EC2 上或本地服务器上迁移](#ec2-onprem-migration) + [在 Amazon ECS 上迁移](#ecs-migration) + [在 Elastic Beanstalk 上迁移](#beanstalk-migration) ### 在 Amazon EC2 上或本地服务器上迁移 **重要** 在使用 CloudWatch 代理或 OpenTelemetry 收集器之前，请停止 X-Ray Daemon 进程，以防止端口冲突。 #### 现有的 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 进程守护程序是通过以下任一方式配置的： + 命令行参数 + 配置文件（`xray-daemon.yaml`） **Example 使用配置文件** ``` ./xray -c ~/xray-daemon.yaml ``` ##### 运行进程守护程序 您当前使用的 X-Ray 进程守护程序是通过以下命令启动的： ``` ~/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 接收器 从您的应用程序中收集跟踪数据 + X-Ray 导出程序 将跟踪数据发送到 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`权限配置 Amazon 凭证。有关更多信息，请参阅[指定凭证](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 Daemon 容器，以防止端口冲突。 #### 使用代 CloudWatch 理 1. 从 [Amazon ECR 公开映像浏览馆](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 Parameter Store 中： 1. 打开 [https://console.aws.amazon.com/systems-manager/](https://console.amazonaws.cn/systems-manager/) 1. 选择**创建参数** 1. 输入以下值： + 名称: `/ecs/cwagent/otel-config` + 层级：标准 + 类型：字符串 + 数据类型：文本 + 值：[将 cw-agent-otel .json 配置粘贴到此处] 1. 使用桥式网络模式创建任务定义： 在您的任务定义中，配置取决于您使用的联网模式。桥式联网是默认模式，可在您的默认 VPC 中使用。在桥接网络中，设置`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`环境变量以告诉 S OpenTelemetry DK CloudWatch 代理的端点和端口。您还应该创建一个从应用程序容器到 Collector 容器的链接，以便将跟踪从应用程序中的 OpenTelemetry SDK 发送到 Collector 容器。 **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" } ] } ] } ``` 有关更多信息，请参阅[在 Amazon ECS 上部署 CloudWatch 代理以收集 Amazon ECS 上的 Amazon EC2 实例级别指标](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/deploy-container-insights-ECS-instancelevel.html)。 #### 使用 OpenTelemetry 收集器 1. 从 [Docker Hub](https://hub.docker.com/r/otel/opentelemetry-collector-contrib) 获取 Docker 映像 `otel/opentelemetry-collector-contrib`。 1. 使用与 **Amazon EC2 配置收集器**部分相同的内容创建名为 `otel-collector-config.yaml` 的配置文件，但要更新端点以使用 `0.0.0.0` 而不是 `127.0.0.1`。 1. 要在 Amazon ECS 中使用此配置，您可以将配置存储在 Systems Manager Parameter Store 中。首先，前往 Systems Manager Parameter Store 控制台，然后选择**创建新参数**。创建包含以下信息的新参数： + 名称：/ecs/otel/config（收集器的任务定义中将引用此名称） + 层级：标准 + 类型：字符串 + 数据类型：文本 + 值：[将 otel-collector-config .yaml 配置粘贴到此处] 1. 以桥接网络模式为例，创建部署 OpenTelemetry 收集器的任务定义。 在任务定义中，配置取决于您使用的联网模式。桥式联网是默认模式，可在您的默认 VPC 中使用。在桥接网络中，设置`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`环境变量以告诉 S OpenTelemetry DK OpenTelemetry 收集器的端点和端口。您还应该创建一个从应用程序容器到 Collector 容器的链接，以便将跟踪从应用程序中的 OpenTelemetry SDK 发送到 Collector 容器。 **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. 在 `.ebextensions` 目录中创建一个包含以下内容的名为 `cloudwatch.config` 的文件： ``` 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)。