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

# 正在对您的应用程序进行检测 AWS X-Ray
<a name="xray-instrumenting-your-app"></a>

**注意**  
X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， AWS X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 AWS 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](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 检测 OpenTelemetry](#xray-instrumenting-opentel)
+ [使用以下方法对您的应用程序进行检测 AWS X-Ray SDKs](#xray-instrumenting-xray-sdk)
+ [在 AWS Distro for 和 X-Ray OpenTelemetry 之间进行选择 SDKs](#xray-instrumenting-choosing)

## 使用发行版对您的应用程序进行 AWS 检测 OpenTelemetry
<a name="xray-instrumenting-opentel"></a>

 OpenTelemetry (ADOT) AWS 发行版是基于云原生计算基金会 (CNCF) 项目的 AWS 发行版。 OpenTelemetry OpenTelemetry 提供一组开源 APIs、库和代理，用于收集分布式跟踪和指标。该工具包是上游 OpenTelemetry 组件的发行版 SDKs，包括经过测试、优化、保护和支持的 AWS自动检测代理和收集器。

借助 ADOT，工程师只需对应用程序进行一次检测，即可将相关的指标和跟踪发送到多个 AWS 监控解决方案 CloudWatch AWS X-Ray，包括亚马逊和亚马逊 OpenSearch 服务。

将 X-Ray 与 ADOT 配合使用需要两个组件：启用 *OpenTelemetry SDK* 以与 X-Ray 配合使用，以及启用 Collecto * OpenTelemetry r 的AWS Distro 以*与 X-Ray 配合使用。有关将 AWS Distro OpenTelemetry 用于 with AWS X-Ray 和 other 的更多信息 AWS 服务，请参阅[AWS 文档发行版。 OpenTelemetry ](https://aws-otel.github.io/docs/introduction)

有关语言支持和用法的更多信息，请参阅[上的 O AWS bservability。 GitHub](https://github.com/aws-observability)

**注意**  
现在，您可以使用 CloudWatch 代理从 Amazon EC2 实例和本地服务器收集指标、日志和跟踪。 CloudWatch 代理版本 1.300025.0 及更高版本可以从我们的 X-Ray 客户端收集痕迹 SDKs，然后将其发送到 [OpenTelemetry](#xray-instrumenting-opentel)[X-R](#xray-instrumenting-xray-sdk) ay。使用 CloudWatch 代理代替 AWS Distro for OpenTelemetry (ADOT) Collector 或 X-Ray 守护程序来收集跟踪可以帮助您减少管理的代理数量。有关更多信息，请参阅《 CloudWatch 用户指南》中的[CloudWatch 代理](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)主题。

ADOT 包括以下内容：
+ [AWS Go 发行 OpenTelemetry 版](https://aws-otel.github.io/docs/getting-started/go-sdk)
+ [AWS 适用于 Java 的 OpenTelemetry 发行版](https://aws-otel.github.io/docs/getting-started/java-sdk)
+ [AWS 发行版适用于 OpenTelemetry JavaScript](https://aws-otel.github.io/docs/getting-started/javascript-sdk)
+ [AWS 适用于 Python 的 OpenTelemetry 发行版](https://aws-otel.github.io/docs/getting-started/python-sdk)
+ [AWS .NET 发行 OpenTelemetry 版](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 托管 Lambd AWS a 层使用 Java、Node.js 和 Python 运行时对 Lambda 函数及其下游请求进行自动检测。](https://aws-otel.github.io/docs/getting-started/lambda)

 SDKs 适用于 Java 和 Go 的 ADOT 支持 X-Ray 集中采样规则。如果您需要支持其他语言的 X-Ray 采样规则，请考虑使用 S AWS X-Ray DK。

**注意**  
你现在可以发送发送 W3C 跟踪 IDs 到 X-Ray。默认情况下，使用创建的跟踪 OpenTelemetry 具有基于 [W3C 跟踪上下文规范的跟踪](https://www.w3.org/TR/trace-context/) ID 格式。这与使用 X-Ray SDK 或与 X-Ray 集成的 AWS 服务创建的跟踪 IDs 格式不同。[为确保 X-Ray 接受 W3C 格式的跟踪 IDs ，您必须使用AWS X-Ray Exporter 版本 0.86.0 或更高版本，该版本包含在 [ADOT Collector](https://aws-otel.github.io/download) 版本 0.34.0 及更高版本中。](https://aws-otel.github.io/docs/getting-started/x-ray)先前版本的导出器会验证跟踪 ID 时间戳，这可能会导致 W3C 跟踪被 IDs 拒绝。

## 使用以下方法对您的应用程序进行检测 AWS X-Ray SDKs
<a name="xray-instrumenting-xray-sdk"></a>

 AWS X-Ray 包括一组特定于语言的工具， SDKs 用于对您的应用程序进行检测以向 X-Ray 发送跟踪。每个 X-Ray SDK 都提供以下内容：
+ *拦截器*，可添加到您的代码中以跟踪传入 HTTP 请求
+ *客户端处理程序，用于检*测 AWS SDK 客户端，您的应用程序使用这些客户端来调用其他客户端 AWS 服务
+ *HTTP 客户端*，用于检测对其他内部和外部 HTTP Web 服务的调用

X-Ray SDKs 还支持对 SQL 数据库进行检测调用、自动 AWS SDK 客户端检测以及其他功能。该 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 的 SDK](xray-sdk-java.md)
+ [AWS X-Ray Node.js 的软件开发工具包](xray-sdk-nodejs.md)
+ [AWS X-Ray Python 软件开发工具包](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 和 X-Ray OpenTelemetry 之间进行选择 SDKs
<a name="xray-instrumenting-choosing"></a>

 X-Ray SDKs 随附的设备是提供的紧密集成的仪器解决方案的一部分 AWS。的 AWS 发行版 OpenTelemetry 是更广泛的行业解决方案的一部分，在该解决方案中，X-Ray 只是众多追踪解决方案之一。您可以使用任何一种方法在 X-Ray 中实现 end-to-end跟踪，但要确定最有用的方法，请务必了解其中的差异。

 OpenTelemetry 如果您需要以下内容，我们建议您使用 AWS Distro 来测试您的应用程序：
+ 无需重新检测代码即可将跟踪信息发送到多个不同的跟踪后端
+ Support 支持每种语言的大量图书馆工具，由社区维护 OpenTelemetry
+ 完全托管的 Lambda 层，使用 Java、Python 或 Node.js 时无需更改代码即可打包收集遥测数据所需的一切
**注意**  
AWS Distro for 为你的 Lambda 函数 OpenTelemetry 提供了更简单的入门体验。但是，由于 OpenTelemetry 提供的灵活性，您的 Lambda 函数将需要额外的内存，并且调用可能会遇到冷启动延迟增加的情况，这可能会导致额外费用。如果您正在针对低延迟进行优化，并且不需要 OpenTelemetry的高级功能，例如可动态配置的后端目标，则可能需要使用 AWS X-Ray SDK 来检测您的应用程序。

 如果您有以下需求，建议选择 X-Ray SDK 来检测应用程序：
+ 紧密集成的单一供应商解决方案
+ 与 X-Ray 集中采样规则集成，包括在 Node.js、Python、Ruby 或 .NET 时，能够从 X-Ray 控制台配置采样规则，以及跨多主机自动使用这些规则