从 X-Ray 仪器迁移到 OpenTelemetry 仪器 - AWS X-Ray

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

从 X-Ray 仪器迁移到 OpenTelemetry 仪器

X-Ray 正在过渡到 OpenTelemetry (OTel) 作为其应用跟踪和可观察性的主要仪器标准。这种战略转变 AWS 符合行业最佳实践,为客户提供了更全面、更灵活和面向未来的解决方案,以满足他们的可观察性需求。 OpenTelemetry它在业界得到广泛采用,可以跨不同的系统追踪请求,包括 AWS 那些可能无法直接与 X-Ray 集成的外部系统。

本章为平稳过渡提供了建议,并强调了迁移到 OpenTelemetry基于解决方案的重要性,以确保持续支持和访问应用程序仪器和可观察性方面的最新功能。

建议将其 OpenTelemetry 用作检测应用程序的可观察性解决方案。

理解 OpenTelemetry

OpenTelemetry 是一个行业标准的可观测性框架,它提供了用于收集遥测数据的标准化协议和工具。它提供了一种统一的方法来检测、生成、收集和导出遥测数据,例如指标、日志和跟踪。

从 X-Ray 迁移 SDKs 到时 OpenTelemetry,您将获得以下好处:

  • 增强的框架和库工具支持

  • Support 支持其他编程语言

  • 自动仪表功能

  • 灵活的采样配置选项

  • 统一收集指标、日志和跟踪

与 X-Ray 守护程序相比,收集 OpenTelemetry 器为数据收集格式和导出目标提供了更多的选项。

OpenTelemetry 支持 AWS

AWS 为处理以下问题提供了多种解决方案 OpenTelemetry:

  • AWS 发行版适用于 OpenTelemetry

    将 OpenTelemetry 轨迹作为分段导出到 X-Ray。

    有关更多信息,请参阅AWS 发行版。 OpenTelemetry

  • CloudWatch 应用程序信号

    导出自定义 OpenTelemetry 跟踪和指标以监控应用程序运行状况。

    有关更多信息,请参阅使用应用程序信号

  • CloudWatch OTel 端点

    使用带有本机 OpenTelemetry 仪器的 HTTP OTel 端点将 OpenTelemetry 跟踪导出到 X-Ray。

    有关更多信息,请参阅使用 OTel 终端节点

OpenTelemetry 与一起使用 AWS CloudWatch

AWS CloudWatch 支持 OpenTelemetry 通过客户端应用程序工具和本机 AWS CloudWatch 服务(例如应用程序信号、跟踪、地图、指标和日志)进行跟踪。有关更多信息,请参阅 OpenTelemetry

了解迁移 OpenTelemetry 概念

下表将 X-Ray 概念映射到它们的 OpenTelemetry 等效概念。了解这些映射有助于您将现有的 X-Ray 仪器转换为 OpenTelemetry:

X 射线概念 OpenTelemetry 概念
X-Ray 记录器 示踪剂提供者和示踪剂
服务插件 资源探测器
客户细分 (服务器)跨度
子细分市场 (非服务器)跨度
X 射线采样规则 OpenTelemetry 采样(可定制)
X-Ray 发射器 Span 导出器(可定制)
注释/元数据 Attributes
图书馆仪器 图书馆仪器
X-Ray 追踪背景 跨度上下文
X-Ray 轨迹上下文传播 W3C 跟踪上下文传播
X 射线痕迹采样 OpenTelemetry 轨迹采样
不适用 跨度处理
不适用 行李
X-Ray 守护程序 OpenTelemetry 收藏家
注意

有关 OpenTelemetry 概念的更多信息,请参阅OpenTelemetry 文档

比较功能

下表显示了这两种服务都支持哪些功能。使用此信息来确定迁移期间需要解决的任何差距:

功能 X 射线仪器 OpenTelemetry 仪器
图书馆仪器 支持 支持
X 射线采样 支持

在 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,你需要一个示踪剂。您可以通过在应用程序中初始化 Trac er 提供者来获得示踪器。这与使用 X-Recorder 配置 X-Recorder 以及在 X-Ray 轨迹中创建分段和子分段的方式类似。

注意

与 X-Ray Record OpenTelemetry er 相比,Tracer Provider 提供了更多的配置选项。

了解轨迹数据结构

在了解了基本概念和功能映射之后,您可以了解特定的实现细节,例如跟踪数据结构和采样。

OpenTelemetry 使用跨度而不是分段和子分段来构造跟踪数据。每个跨度包括以下组件:

  • 名称

  • 唯一标识

  • 开始和结束时间戳

  • 跨度种类

  • 跨越上下文

  • 属性(键值元数据)

  • 事件(带时间戳的日志)

  • 指向其他跨度的链接

  • 状态信息

  • 父跨度引用

迁移到时 OpenTelemetry,您的跨度会自动转换为 X-Ray 分段或子分段。这样可以确保您现有的主 CloudWatch 机体验保持不变。

使用跨度属性

X-Ray SDK 提供了两种向区段和子分段添加数据的方法:

Annotations

为筛选和搜索编制索引的键值对

元数据

包含未编入索引以供搜索的复杂数据的键值对

默认情况下, OpenTelemetry 跨度属性会转换为 X-Ray 原始数据中的元数据。要改为将特定属性转换为注释,请将其键添加到aws.xray.annotations属性列表中。

检测环境中的资源

OpenTelemetry 使用资源检测器收集有关生成遥测数据的资源的元数据。此元数据存储为资源属性。例如,生成遥测数据的实体可以是 Amazon ECS 集群或 Amazon EC2 实例,可以从这些实体记录的资源属性可以包括 Amazon ECS 集群 ARN 或 EC2 亚马逊实例 ID。

管理抽样策略

跟踪采样通过从具有代表性的请求子集而不是所有请求中收集数据来帮助您管理成本。 OpenTelemetry 和 X-Ray 都支持采样,但实现方式有所不同。

注意

采样少于 100% 的轨迹可以降低可观察性成本,同时保持对应用程序性能的有意义的见解。

OpenTelemetry 提供了多种内置采样策略,并允许您创建自定义采样策略。您还可以使用某些 SDK 语言配置 X-Remote Sampler,以便使用 X-Ray 采样规则。 OpenTelemetry

来自的其他抽样策略 OpenTelemetry 有:

  • 基于父母的抽样 — 在应用其他抽样策略之前,请尊重父跨度的抽样决定

  • 基于跟踪 ID 比率的采样 — >随机抽取指定百分比的跨度

  • 尾部采样 — 将采样规则应用于 OpenTelemetry 收集器中的完整轨迹

  • 自定义采样器 — 使用采样接口实现自己的采样逻辑

有关 X-Ray 采样规则的信息,请参阅 X-Ra y 控制台中的采样规则

有关 OpenTelemetry 尾部采样的信息,请参见尾部采样处理器

管理追踪上下文

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 跟踪的 AWS 服务发送跟踪上下文。

配置并使用 X-Ray Propagator 启用跨 AWS 服务的跟踪。这允许您将跟踪上下文传播到 API Gateway 端点和其他支持 X-Ray 的服务。

  • 有关 X-Ray 跟踪标头的信息,请参阅 X-Ray 开发人员指南中的跟踪标

  • 有关 OpenTelemetry 上下文传播的信息,请参阅 OpenTelemetry 文档中的上下文和上下文传播

使用图书馆工具

X-Ray 和 X-Ray 都 OpenTelemetry 提供了库工具,只需最少的代码更改即可向应用程序添加跟踪。

X-Ray 提供图书馆仪器功能。这允许您添加预先构建的 X-Ray 仪器,而只需对应用程序代码进行最少的更改。这些工具支持特定的库,例如 AWS SDK 和 HTTP 客户端,以及 Spring Boot 或 Express.js 等网络框架。

OpenTelemetry的工具库通过库挂钩或自动代码修改为您的库生成详细的跨度,只需最少的代码更改。

要确定 OpenTelemetry's Library Instrumentations是否支持您的库,请在 OpenTelemetry 注册表的注册表中进行搜索。OpenTelemetry

导出轨迹

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 射线追踪处理

X-Ray Daemon 处理跟踪处理:

  • 监听来自 X-Ray 的 UDP 流量 SDKs

  • 批量区段和子细分

  • 将批量上传到 X-Ray 服务

OpenTelemetry 跟踪处理

OpenTelemetry 收集器处理追踪处理:

  • 接收来自仪器化服务的跟踪

  • 处理并可选择修改跟踪数据

  • 将处理过的跟踪发送到各种后端,包括 X-Ray

注意

AWS CloudWatch 代理还可以接收 OpenTelemetry 轨迹并将其发送到 X-Ray。有关更多信息,请参阅使用收集指标和跟踪 OpenTelemetry

跨度处理(OpenTelemetry特定概念)

OpenTelemetry 使用跨度处理器在创建跨度时对其进行修改:

  • 允许在创建或完成时读取和修改跨度

  • 启用跨度处理的自定义逻辑

行李(OpenTelemetry特定概念)

OpenTelemetry的行李功能允许传播键值数据:

  • 允许在跟踪上下文旁边传递任意数据

  • 对于跨服务边界传播特定于应用程序的信息很有用

有关 OpenTelemetry 收集器的信息,请参见OpenTelemetry 收集器

有关 X-Ray 概念的信息,请参阅《X-Ray 开发者指南》中的 X-Ray 概念

迁移概述

本节概述了迁移所需的代码更改。以下列表是特定语言的指导和 X-Ray Daemon 迁移步骤。

重要

要从 X-Ray 仪器完全迁移到 OpenTelemetry 仪器,您需要:

  1. 用 OpenTelemetry 解决方案取代 X-Ray SDK 的使用

  2. 将 X-Ray 守护程序替换为 CloudWatch 代理或 OpenTelemetry 收集器(使用 X-Ray 导出器)

针对新应用程序和现有应用程序的建议

对于新的和现有的应用程序,建议使用以下解决方案在应用程序中启用跟踪:

Instrumentation
  • OpenTelemetry SDKs

  • AWS 仪器仪表发行 OpenTelemetry 版

数据收集
  • OpenTelemetry 收藏家

  • CloudWatch 代理人

迁移到 OpenTelemetry基于基础的解决方案后,您的 CloudWatch 体验将保持不变。您仍然可以在 CloudWatch 控制台的 Traces 和 Trace Map 页面中以相同格式查看您的踪迹,或者通过 X- Ray 检索您的跟踪数据 APIs。

跟踪设置更改

您需要用设置替换 X-Ray OpenTelemetry 设置。

X-Ray 和 OpenTelemetry 设置的比较
功能 X-ray SDK OpenTelemetry
默认配置
  • X-Ray 集中采样

  • X-Ray 轨迹上下文传播

  • 跟踪导出到 X-Ray 守护程序

  • 将跟踪导出到 OpenTelemetry 收集器或 CloudWatch 代理 (http/gRPC)

  • W3C 跟踪上下文传播

手动配置
  • 本地抽样规则

  • 资源检测插件

  • X-Ray 采样(可能不适用于所有语言)

  • 资源检测

  • X-Ray 轨迹上下文传播

图书馆工具变更

更新您的代码,使用 OpenTelemetry 库工具代替 AWS SDK、HTTP 客户端、Web 框架和其他库的 X-Ray 库工具。这会生成 OpenTelemetry 轨迹而不是 X-Ray 轨迹。

注意

代码更改因语言和库而异。有关详细说明,请参阅特定语言的迁移指南。

Lambda 环境工具变更

要 OpenTelemetry 在 Lambda 函数中使用,请选择以下设置选项之一:

  1. 使用自动插入 Lambda 层:

  2. 手动设置您 OpenTelemetry 的 Lambda 函数:

    • 使用 X-Ray UDP 跨度导出器配置简单跨度处理器

    • 设置 X-Ray Lambda 传播器

手动创建跟踪数据

将 X-Ray 分段和子分段替换为 OpenTelemetry Span:

  • 使用示 OpenTelemetry 踪剂创建跨度

  • 向 Span 添加属性(等同于 X-Ray 元数据和注释)

重要

发送到 X-Ray 时:

  • 服务器跨度转换为 X-Ray 片段

  • 其他跨度转换为 X-Ray 子分段

  • 默认情况下,属性会转换为元数据

要将属性转换为注释,请将其密钥添加到aws.xray.annotations属性列表中。有关更多信息,请参阅启用自定义 X-Ray 注释

从 X-Ray Daemon 迁移到 AWS CloudWatch 代理或收集器 OpenTelemetry

您可以使用 CloudWatch 代理或 OpenTelemetry 采集器从装有仪器的应用程序接收跟踪并将其发送到 X-Ray。

注意

CloudWatch 代理版本 1.300025.0 及更高版本可以收集跟踪。 OpenTelemetry 使用 CloudWatch 代理代替 X-Ray Daemon 可以减少需要管理的代理数量。有关更多信息,请参阅使用 CloudWatch 代理收集指标、日志和跟踪

在 Amazon EC2 或本地服务器上迁移

重要

在使用 CloudWatch 代理或 OpenTelemetry 收集器之前,请停止 X-Ray Daemon 进程,以防止端口冲突。

现有的 X-Ray 守护程序设置

安装守护程序

您现有的 X-Ray Daemon 用法是使用以下方法之一安装的:

手动安装

从 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)

例 使用配置文件
./xray -c ~/xray-daemon.yaml
运行进程守护程序

您现有的 X-Ray Daemon 使用是通过以下命令开始的:

~/xray-daemon$ ./xray -o -n us-east-1
正在移除守护程序

要从您的亚马逊 EC2 实例中删除 X-Ray Daemon,请执行以下操作:

  1. 停止守护程序服务:

    systemctl stop xray
  2. 删除配置文件:

    rm ~/path/to/xray-daemon.yaml
  3. 如果已配置,请删除日志文件:

    注意

    日志文件位置取决于您的配置:

    • 命令行配置:/var/log/xray-daemon.log

    • 配置文件:检查LogPath设置

设置代 CloudWatch 理

安装座席

有关安装说明,请参阅在本地服务器上安装 CloudWatch 代理

配置代理
  1. 创建配置文件以启用跟踪收集。有关更多信息,请参阅创建 CloudWatch 代理配置文件

  2. 设置 IAM 权限:

    • 为代理附加 IAM 角色或指定证书。有关更多信息,请参阅设置 IAM 角色

    • 确保一个或多个角色凭证包含xray:PutTraceSegments权限。

启动 代理

有关启动代理的说明,请参阅使用命令行启动 CloudWatch 代理。

设置 OpenTelemetry 收集器

安装收集器

下载并安装适用于您的操作系统的 OpenTelemetry 收集器。有关说明,请参阅安装收集器

配置收集器

在收集器中配置以下组件:

  • awsproxy 扩展

    X-Ray 采样所必需的

  • OTel 接收器

    从您的应用程序中收集痕迹

  • X 射线导出器

    向 X-Ray 发送轨迹

例 采集器配置示例 — 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 凭证。有关更多信息,请参阅指定凭据

启动收集器

使用您的配置文件运行收集器:

otelcol --config=otel-collector-config.yaml

在 Amazon ECS 上迁移

重要

您的任务角色必须拥有您使用的任何收集器的xray:PutTraceSegments权限。

在同一台主机上运行 CloudWatch 代理或 OpenTelemetry 收集器容器之前,请停止任何现有的 X-Ray Daemon 容器,以防止端口冲突。

使用代 CloudWatch 理

  1. 亚马逊 ECR 公共画廊获取 Docker 图片。

  2. 创建名为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" } } } }
  3. 将配置存储在 Systems Manager 参数存储中:

    1. 打开 https://console.aws.amazon.com/systems-manager/

    2. 选择 “创建参数”

    3. 输入以下值:

      • 名称: /ecs/cwagent/otel-config

      • 等级:标准

      • 类型:字符串

      • 数据类型:文本

      • 值:[将 cw-agent-otel .json 配置粘贴到此处]

  4. 使用桥接网络模式创建任务定义:

    在您的任务定义中,配置取决于您使用的联网模式。桥式联网是默认模式,可在您的默认 VPC 中使用。在桥接网络中,设置OTEL_EXPORTER_OTLP_TRACES_ENDPOINT环境变量以告诉 OpenTelemetry SDK CloudWatch 代理的终端节点和端口。您还应该创建一个从应用程序容器到 Collector 容器的链接,以便将跟踪从应用程序中的 OpenTelemetry SDK 发送到 Collector 容器。

    例 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 EC2 实例级指标

使用 OpenTelemetry 收集器

  1. otel/opentelemetry-collector-contrib从 Docker Hub 获取 Docker 镜像。

  2. otel-collector-config.yaml使用与 Amazon 配置收集器部分相同的内容创建名为的 EC2 配置文件,但要更新终端节点以0.0.0.0代替127.0.0.1

  3. 要在 Amazon ECS 中使用此配置,您可以将配置存储在 Systems Manager 参数存储中。首先,前往 Systems Manager 参数存储控制台,然后选择创建新参数。使用以下信息创建新参数:

    • 名称:/ecs/otel/config(收集器的任务定义中将引用此名称)

    • 等级:标准

    • 类型:字符串

    • 数据类型:文本

    • 值:[将 otel-collector-config .yaml 配置粘贴到此处]

  4. 以桥接网络模式为例,创建部署 OpenTelemetry 收集器的任务定义。

    在任务定义中,配置取决于您使用的联网模式。桥式联网是默认模式,可在您的默认 VPC 中使用。在桥接网络中,设置OTEL_EXPORTER_OTLP_TRACES_ENDPOINT环境变量以告诉 S OpenTelemetry DK OpenTelemetry 收集器的端点和端口。您还应该创建一个从应用程序容器到 Collector 容器的链接,以便将跟踪从应用程序中的 OpenTelemetry SDK 发送到 Collector 容器。

    例 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 Daemon 集成是通过使用 Elastic Beanstalk 控制台开启的,或者通过使用配置文件在应用程序源代码中配置 X-Ray Daemon。

使用代 CloudWatch 理

在 Amazon Linux 2 平台上,使用.ebextensions配置文件配置 CloudWatch 代理:

  1. 在项目根目录.ebextensions中创建一个名为的目录

  2. .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
  3. 部署时将该.ebextensions目录包含在应用程序源包中

有关 Elastic Beanstalk 配置文件的更多信息,请参阅使用配置文件进行高级环境自定义。