如何解决服务地图中 X-Ray 跟踪丢失、分段遗漏或服务欠缺的问题？

简述

丢失跟踪信息会导致服务地图中缺少服务。以下是导致丢失跟踪信息的原因：

• 未正确检测
• X-Ray SDK 无法通过进程守护程序地址或端口号访问 X-Ray 进程守护程序
• X-Ray 进程守护程序无法访问 X-Ray 服务端点
• 未在单独服务级别配置跟踪
• 缺少 AWS Identity and Access Management（IAM）权限
• 采样规则配置
• OpenTelemetry Collector 中缺少配置

子分段没有对应的开放父分段会导致缺少分段。有关更多信息，请参阅 Troubleshooting AWS X-Ray。

解决方法

未正确检测

使用 X-Ray SDK 时未正确检测

如果您的应用程序代码没有针对使用 X-Ray SDK 进行正确检测，以修补支持的库和框架，那么您可能会丢失跟踪信息。跟踪 ID 未传递给下游服务也会导致丢失跟踪信息。

要解决此问题，请在 SDK 上开启调试级日志记录，将更详细的日志输出到应用程序日志文件中。这样，您就可以进一步隔离与检测相关的问题，并且对整个应用程序中该跟踪 ID 的流进行跟踪。日志还会显示丢失跟踪信息的原因是未对跟踪进行采样，还是因为检测配置错误。有关更多信息，请查看适用于 Java、Node.js、Python、.NET 或 Ruby 的 X-Ray SDK 中的调试日志。

**注意：**如果应用程序使用适用于 Java 的自动检测代理，则不会捕获异步请求的跟踪，因此将丢失跟踪。如果您丢失跟踪信息，请使用手动检测。如果 X-Ray SDK 缺少某些功能或存在问题，请查看 OpenTelemetry SDK 中是否有适用于 Java 的自动检测代理。

使用 OpenTelemetry SDK 时未正确检测

如果您使用 OpenTelemetry SDK，但应用程序代码未得到正确地检测以修补支持的库和框架，则应用程序代码可能会丢失跟踪信息。跟踪 ID 未传递给下游服务也会导致分段丢失。

要排查此问题，请采取以下措施：

• 在 SDK 上开启调试级日志记录，将更详细的日志发送到应用程序日志文件中。这样，您就可以进一步隔离与检测相关的问题，并且对整个应用程序中该跟踪 ID 的流进行跟踪。日志显示丢失跟踪信息的原因是未对跟踪进行采样，还是因为检测配置错误。有关更多信息，请查看适用于 Java、Node.js、Python、.NET 或 Ruby 的 X-Ray SDK 中的调试日志。
• 确保未关闭检测。有关更多信息，请参阅 OpenTelemetry 网站上的 Suppressing specific auto-instrumentation。

**注意：**要使用 AWS 基础设施信息丰富跟踪信息，请确保 OpenTelemetry SDK 中的相应 AWS 服务支持 AWS 资源检测器。有关更多信息，请参阅Using the AWS resource detectors。

X-Ray SDK 无法通过进程守护程序地址或端口号访问 X-Ray 进程守护程序

如果 X-Ray SDK 无法通过默认或配置的进程守护程序端口号和地址访问 X-Ray 进程守护程序，则 SDK 将丢失跟踪。X-Ray 进程守护程序地址通过 AWS_XRAY_DAEMON_ADDRESS 环境变量传递至 SDK。默认情况下，X-Ray 进程守护程序侦听端口 2000 UDP。您可以通过命令行选项和传递给 X-Ray 进程守护程序的配置文件来更改此端口。有关更多信息，请参阅Using a configuration file。

如果您运行 X-Ray 进程守护程序时开启了调试日志，请运行以下命令来识别为 X-Ray 进程守护程序配置的 UDP 端口：

./xray -l debug

**注意：**以下示例将识别端口号为 3000。

输出示例：

2023-03-28T15:15:43-07:00 \[Debug\] Listening on UDP 127.0.0.1:3000

如果您运行 X-Ray 进程守护程序时没有开启调试日志，请先启用调试日志选项，然后重新运行该进程守护程序。有关更多信息，请参阅Using a configuration file。

**注意：**如果您的 X-Ray 进程守护程序与应用程序和 X-Ray SDK 不在同一台机器上运行，请检查入站规则和入口规则。确认安全组入站规则和网络访问控制列表（网络 ACL）入口规则是否允许流量通过。您必须允许 X-Ray SDK 通过 X-Ray 进程守护程序的侦听器端口进行通信。

X-Ray 进程守护程序无法访问 X-Ray 服务端点

如果 X-Ray 进程守护程序无法访问 X-Ray 服务端点，请采取以下措施：

• 如果您在源端配置了代理，请检查该代理是否没有允许流量通过 X-Ray 服务端点。
• 如果使用 Amazon Virtual Private Cloud（Amazon VPC）端点 com.amazonaws.region.xray 连接到 X-Ray 服务，请检查附加的安全组。确保安全组允许出站流量，允许 HTTPS 流量将数据推送到 X-Ray 服务 API。此外，请确保安全组允许端口 443 上的入站流量，以允许使用 X-Ray 进程守护程序。
• 验证关联的网络 ACL 和 X-Ray Amazon VPC 端点是否具有允许端口 443 上的流量通过 0.0.0.0/0 的出口规则。X-Ray 进程守护程序必须将数据发送到 X-Ray 服务端点。此外，验证网络 ACL 入口规则是否允许流量从 X-Ray 进程守护程序流向 Amazon VPC 端点。

未在单独服务级别配置跟踪

如果您没有为某些 AWS 服务启用 X-Ray 配置，则可能会丢失跟踪信息。以下是需要在服务级别启用 X-Ray 配置的 AWS 服务列表：

• AWS AppSync
• AWS App Runner
• Amazon API Gateway
• Amazon CloudWatch RUM
• AWS Lambda
• Amazon Simple Notification Service (Amazon SNS)
• AWS Step Functions

缺少 IAM 权限

确认您拥有所需的 IAM 权限：

• 如果您在 X-Ray 进程守护程序日志中看到Access Denied错误，请检查 IAM 权限。要向 X-Ray 服务端点发送跟踪信息，X-Ray 进程守护程序 IAM 角色需要 AWSXRAYDaemonWriteAccess 托管策略中的权限。如果您在 IAM policy 中使用基于标签的条件，请确保 IAM policy 引用的标签正确无误。有关更多信息，请参阅Authorization based on X-Ray tags。
• 如果 X-Ray 进程守护程序作为任务中的 Sidecar 容器在 Amazon Elastic Container Service（Amazon ECS）中运行，请检查 Amazon ECS 任务角色。确保 Amazon ECS 任务角色附加了 AWSXRayDaemonWriteAccess 策略。
• 如果您是在 Amazon Elastic Kubernetes Services（Amazon EKS）中部署 X-Ray 进程守护程序，请检查容器组（pod）中的 Sidecar 容器。确保容器使用针对服务账户的 IAM 角色（IRSA），并且 AWSXRayDaemonWriteAccess 策略已附加到该 IAM 角色。
• 如果您是在 Amazon Elastic Compute Cloud（Amazon EC2）中配置 X-Ray 进程守护程序，请检查关联的实例配置文件。确保与该 EC2 实例关联的实例配置文件角色附加了 AWSXRayDaemonWriteAccess 策略。
• 如果您是在 AWS Lambda 中配置 X-Ray 进程守护程序，则检查 Lambda 执行角色。确认 Lambda 执行角色是否具有 AWSXRayDaemonWriteAccess 策略。确保已附加该策略。
• 如果您在 Amazon SNS 中开启了主动跟踪，但仍然看不到跟踪信息，请在 X-Ray 中配置资源策略。

**注意：**要确认 X-Ray 权限，请使用 IAM policy simulator 测试您的 IAM 角色或附加到资源的策略。此外，请检查组织的服务控制策略（SCP）。SCP 在账户级别限制特定 API 调用的访问权限。

有关 X-Ray 的 IAM 托管策略列表，请参阅 IAM managed policies for X-Ray。

采样规则配置

如果支持带采样配置的主动跟踪的 X-Ray SDK 和 AWS 服务没有采样跟踪信息，那么您可能会丢失跟踪信息。使用采样规则来确定要记录的请求。默认情况下，X-Ray SDK 记录每秒钟的第一个请求，以及其他所有请求中的 5%。您可以更改采样率以减少或增加记录的跟踪数量。

例如，将容器设置为 1。容器为 1 表示会记录每秒钟的第一个请求。或者，将采样率设置为 0.1。采样率为 0.1 表示每秒记录其他请求的 10%。

由于 X-Ray SDK 限制了 SDK 记录的请求数量，因此可能无法跟踪所有请求。要记录更多跟踪，请增加容器大小和提高采样率。有关更多信息，请参阅Sampling rule examples。

**注意：**如果您配置了多个采样规则，并且采样跟踪的数量出现波动，请检查 X-Ray SDK 使用的采样规则。有关更多信息，请参阅Viewing sampling results。

OpenTelemetry Collector 中缺少配置

如果您使用的是 OpenTelemetry Collector 而不是 X-Ray 进程守护程序，则可能缺少所需的接收器和导出器配置。如果缺少配置，则不会向 X-Ray 服务端点发送跟踪信息。根据您的接收器，请检查 config.yaml 文件中的接收器配置，确认未缺少配置。

在 GitHub 网站上查看以下示例配置：

• X-Ray exporter
• X-Ray receiver
• ZipKin receiver

**注意：**确保 AWSXRayDaemonWriteAccess 托管策略中具有所需的 IAM 权限。