本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# AWS X-Ray 守护程序
**注意**
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)。
**注意**
现在，您可以使用 CloudWatch 代理从 Amazon EC2 实例和本地服务器收集指标、日志和跟踪。 CloudWatch 代理版本 1.300025.0 及更高版本可以从我们的 X-Ray 客户端收集痕迹 SDKs，然后将其发送到 [OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel)[X-R](xray-instrumenting-your-app.md#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)主题。
AWS X-Ray 守护程序是一个软件应用程序，它监听 UDP 端口 2000 上的流量，收集原始数据段数据并将其中继到 API。 AWS X-Ray 该守护程序与配合使用， AWS X-Ray SDKs 并且必须处于运行状态，这样发送的数据 SDKs 才能到达 X-Ray 服务。X-Ray 进程守护程序是一个开源项目。你可以关注该项目并在 [github 上 GitHub提交议题和拉取请求。 com/aws/aws-xray-daemon](https://github.com/aws/aws-xray-daemon)
在 and 上 AWS Lambda AWS Elastic Beanstalk，使用这些服务与 X-Ray 的集成来运行守护程序。每次对采样请求调用函数时，Lambda 都会自动运行该进程守护程序。在 Elastic Beanstalk 上，[使用 `XRayEnabled` 配置选项](xray-daemon-beanstalk.md)在您环境中的实例上运行该进程守护程序。有关更多信息，请参阅
要在本地、本地或其他地方运行 X-Ray 守护程序 AWS 服务，[请下载并[运行它](#xray-daemon-running)，然后授予其将分段文档上传到 X-Ray 的权限](#xray-daemon-permissions)。
## 下载进程守护程序
可以从 Amazon S3、Amazon ECR 或 Docker Hub 下载该进程守护程序，然后在本地运行它，或在启动时在 Amazon EC2 实例上安装它。
------
#### [ Amazon S3 ]
**X-Ray 进程守护程序安装程序和可执行文件**
+ **Linux（可执行文件）**- [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zip](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zip)（[sig](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zip.sig)）
+ **Linux（RPM 安装程序）**– [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm)
+ **Linux（DEB 安装程序）**– [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.deb](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.deb)
+ **Linux（ARM64，可执行文件）**— [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-arm64-3.x.zip](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-arm64-3.x.zip)（[签名](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-arm64-3.x.zip.sig)）
+ **Linux（ARM64，RPM 安装程序）**— [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-arm64-3.x.rpm](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-arm64-3.x.rpm)
+ **Linux（ARM64，DEB 安装程序）— [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-arm64-3.x.deb](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-arm64-3.x.deb)**
+ **OS X（可执行文件）**- [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-macos-3.x.zip](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-macos-3.x.zip)（[sig](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-macos-3.x.zip.sig)）
+ **Windows（可执行文件）**– [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-windows-process-3.x.zip](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-windows-process-3.x.zip)（[sig](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-windows-process-3.x.zip.sig)）
+ **Windows（服务）**– [https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip)（[sig](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip.sig)）
这些链接始终指向最新 3.x 版本的进程守护程序。要下载特定版本，请执行以下操作：
+ 如果要下载 `3.3.0` 之前的版本，请将 `3.x` 替换为该版本号。例如 `2.1.0`。在 `3.3.0` 版本之前，唯一可用的架构是 `arm64`。例如，`2.1.0` 和 `arm64`。
+ 如果要下载 `3.3.0` 之后的版本，请将 `3.x` 替换为该版本号，将 `arch` 替换为该架构类型。
X-Ray 资产被复制到每个受支持区域的存储桶。要使用离您最近的存储桶或您的 AWS 资源，请将上述链接中的区域替换为您的区域。
```
https://s3.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-3.x.rpm
```
------
#### [ Amazon ECR ]
从 3.2.0 版本开始，可以在 [Amazon ECR](https://gallery.ecr.aws/xray/aws-xray-daemon) 找到该进程守护程序。在提取映像前，应该先对连接 Amazon ECR 公共注册表的 [Docker 客户端进行身份验证](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html#public-registry-auth)。
运行以下命令提取最新发布的 3.x 版本标签：
```
docker pull public.ecr.aws/xray/aws-xray-daemon:3.x
```
可通过将 `3.x` 替换为 `alpha` 或是某一具体版本号来下载以前的版本或 Alpha 版本。不建议在生产环境中使用带有 Alpha 标签的进程守护程序标签。
------
#### [ Docker Hub ]
可以在 [Docker Hub](https://hub.docker.com/r/amazon/aws-xray-daemon) 上找到该进程守护程序。运行以下命令下载最新发布的 3.x 版本：
```
docker pull amazon/aws-xray-daemon:3.x
```
通过将 `3.x` 替换为想要的版本，可以发布以前版本的进程守护程序。
------
## 验证进程守护程序存档的签名
以 ZIP 存档格式压缩的进程守护程序资产会附带 GPG 签名文件。公有密钥在这里：[https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray.gpg](https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray.gpg)。
您可以使用公有密钥来验证进程守护程序的 ZIP 存档是原始的且未经过修改。首先，使用 [GnuPG](https://gnupg.org/index.html) 导入公有密钥。
**导入公有密钥**
1. 下载公有密钥。
```
$ BUCKETURL=https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2
$ wget $BUCKETURL/xray-daemon/aws-xray.gpg
```
1. 将公有密钥导入到您的密钥环中。
```
$ gpg --import aws-xray.gpg
gpg: /Users/me/.gnupg/trustdb.gpg: trustdb created
gpg: key 7BFE036BFE6157D3: public key "AWS X-Ray " imported
gpg: Total number processed: 1
gpg: imported: 1
```
使用导入的密钥来验证进程守护程序 ZIP 存档的签名。
**验证存档的签名**
1. 下载存档和签名文件。
```
$ BUCKETURL=https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2
$ wget $BUCKETURL/xray-daemon/aws-xray-daemon-linux-3.x.zip
$ wget $BUCKETURL/xray-daemon/aws-xray-daemon-linux-3.x.zip.sig
```
1. 运行 `gpg --verify` 来验证签名。
```
$ gpg --verify aws-xray-daemon-linux-3.x.zip.sig aws-xray-daemon-linux-3.x.zip
gpg: Signature made Wed 19 Apr 2017 05:06:31 AM UTC using RSA key ID FE6157D3
gpg: Good signature from "AWS X-Ray "
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: EA6D 9271 FBF3 6990 277F 4B87 7BFE 036B FE61 57D3
```
请注意有关信任的警告。只有当您或您信任的某个人对文件进行了签名，密钥才是可信的。这并不意味着签名无效，只是您尚未验证公有密钥而已。
## 运行进程守护程序
在本地从命令行运行进程守护程序。使用 `-o` 选项以本地模式运行，`-n` 选项设置区域。
```
~/Downloads$ ./xray -o -n us-east-2
```
有关特定于平台的详细说明，请参阅下列主题：
+ **Linux（本地）**- [在 Linux 上运行 X-Ray 进程守护程序](xray-daemon-local.md#xray-daemon-local-linux)
+ **Windows（本地）**- [在 Windows 上运行 X-Ray 进程守护程序](xray-daemon-local.md#xray-daemon-local-windows)
+ **Elastic Beanstalk** – [正在运行 X-Ray 守护程序 AWS Elastic Beanstalk](xray-daemon-beanstalk.md)
+ **Amazon EC2** – [在亚马逊上运行 X-Ray 守护程序 EC2](xray-daemon-ec2.md)
+ **Amazon ECS** – [在 Amazon ECS 上运行 X-Ray 进程守护程序](xray-daemon-ecs.md)
您可以使用命令行选项或配置文件进一步自定义进程守护程序的行为。有关详细信息，请参阅 [配置 AWS X-Ray 守护程序](xray-daemon-configuration.md)。
## 授予进程守护程序向 X-Ray 发送数据的权限
X-Ray 守护程序使用 AWS SDK 将跟踪数据上传到 X-Ray，它需要有权限的 AWS 凭证才能这样做。
在 Amazon EC 上，进程守护程序自动使用实例的实例配置文件角色。有关在本地运行该进程守护程序所需凭证的相关信息，请参阅[在本地运行应用程序](security_iam_service-with-iam.md#xray-permissions-local)。
如果您在多个位置（凭证文件、实例配置文件或环境变量）指定凭证，SDK 会提供证书链，决定使用哪个凭证。有关向 SDK 提供凭证的更多信息，请参阅《AWS SDK for Go 开发人员指南》**中的[指定凭证](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials)。
进程守护程序的凭证所属的 IAM 角色或用户必须有权代表您写入数据到服务。
+ 要在 Amazon EC2 上使用进程守护程序，请创建新实例配置文件角色，或者为现有角色添加托管策略。
+ 要在 Elastic Beanstalk 上使用进程守护程序，请将托管策略添加到 Elastic Beanstalk 默认实例配置文件角色。
+ 请参阅[在本地运行应用程序](security_iam_service-with-iam.md#xray-permissions-local)，了解如何在本地运行进程守护程序。
有关更多信息，请参阅 [的身份和访问管理 AWS X-Ray](security-iam.md)。
## X-Ray 进程守护程序日志
守护程序输出有关其当前配置和发送到 AWS X-Ray的段的信息。
```
2016-11-24T06:07:06Z [Info] Initializing AWS X-Ray daemon 2.1.0
2016-11-24T06:07:06Z [Info] Using memory limit of 49 MB
2016-11-24T06:07:06Z [Info] 313 segment buffers allocated
2016-11-24T06:07:08Z [Info] Successfully sent batch of 1 segments (0.123 seconds)
2016-11-24T06:07:09Z [Info] Successfully sent batch of 1 segments (0.006 seconds)
```
默认情况下，进程守护程序将日志输出到 STDOUT。如果您在后台运行进程守护程序，请使用 `--log-file` 命令行选项或配置文件来设置日志文件的路径。您也可以设置日志级别并禁用日志轮换。有关说明，请参阅[配置 AWS X-Ray 守护程序](xray-daemon-configuration.md)：
在 Elastic Beanstalk 中，平台将设置进程守护程序日志的位置。有关详细信息，请参阅[正在运行 X-Ray 守护程序 AWS Elastic Beanstalk](xray-daemon-beanstalk.md)。
# 配置 AWS X-Ray 守护程序
**注意**
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)。
您可以使用命令行选项或配置文件来自定义 X-Ray 进程守护程序的行为。大多数选项适用于这两种方法，但有一些只适用于配置文件，有一些只适用于命令行。
要开始使用，您需要知道的唯一选项是 `-n` 或 `--region`，用于设置进程守护程序使用的区域，或将跟踪数据发送到 X-Ray。
```
~/xray-daemon$ ./xray -n us-east-2
```
如果您在本地运行守护程序，也就是说，不是在 Amazon 上 EC2，则可以添加跳过检查实例配置文件凭证的`-o`选项，这样守护程序就可以更快地准备就绪。
```
~/xray-daemon$ ./xray -o -n us-east-2
```
其余的命令行选项可让您配置日志记录、侦听不同端口、限制进程守护程序可以使用的内存量，或代入角色将跟踪数据发送到其他账户。
您可以将配置文件传递到进程守护程序，以访问高级配置选项，并完成其他任务，如限制并发调用 X-Ray 的数量、禁用日志轮换，并将流量发送到代理。
**Topics**
+ [支持的环境变量](#xray-daemon-configuration-variables)
+ [使用命令行选项](#xray-daemon-configuration-commandline)
+ [使用配置文件](#xray-daemon-configuration-configfile)
## 支持的环境变量
X-Ray 进程守护程序支持以下环境变量：
+ `AWS_REGION` — 指定 X-Ray 服务端点的 [AWS 区域](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#cli-quick-configuration-region)。
+ `HTTPS_PROXY` — 为进程守护程序指定一个通过其上传分段的代理地址。它可以是代理服务器使用的 DNS 域名或 IP 地址和端口号。
## 使用命令行选项
当您在本地或使用用户数据脚本运行进程守护程序时，将这些选项传递给它。
**命令行选项**
+ `-b`、`--bind` - 侦听其他 UDP 端口上的分段文档。
```
--bind "127.0.0.1:3000"
```
默认值 – `2000`。
+ `-t`、`--bind-tcp` - 侦听对其他 TCP 端口上的 X-Ray 服务的调用。
```
-bind-tcp "127.0.0.1:3000"
```
默认值 – `2000`。
+ `-c`、`--config` - 从指定路径加载配置文件。
```
--config "/home/ec2-user/xray-daemon.yaml"
```
+ `-f`、`--log-file` - 将日志输出到指定文件路径。
```
--log-file "/var/log/xray-daemon.log"
```
+ `-l`、`--log-level` - 日志级别，依次为从最详细到最不详细：dev、debug、info、warn、error、prod。
```
--log-level warn
```
默认值 – `prod`
+ `-m`、`--buffer-memory` - 更改缓冲区可以使用的内存量（单位：MB，最小值为 3）。
```
--buffer-memory 50
```
默认值 - 1% 的可用内存。
+ `-o`，`--local-mode`— 不检查 EC2 实例元数据。
+ `-r`、`--role-arn` - 采用指定的 IAM 角色将分段上传到其他账户。
```
--role-arn "arn:aws:iam::123456789012:role/xray-cross-account"
```
+ `-a`，`--resource-arn`— 运行守护程序的资源的亚马逊 AWS 资源名称 (ARN)。
+ `-p`，`--proxy-address`— AWS X-Ray 通过代理将区段上传到。必须指定代理服务器的协议。
```
--proxy-address "http://192.0.2.0:3000"
```
+ `-n`、`--region` - 向特定区域中的 X-Ray 服务发送分段。
+ `-v`，`--version`— 显示 AWS X-Ray 守护程序版本。
+ `-h`、`--help` - 显示帮助屏幕。
## 使用配置文件
您也可以使用 YAML 格式文件来配置进程守护程序。使用 `-c` 选项传递配置文件到进程守护程序。
```
~$ ./xray -c ~/xray-daemon.yaml
```
**配置文件选项**
+ `TotalBufferSizeMB` - 最大缓冲区大小（单位：MB，最小值为 3）。选择 0 则使用 1% 的主机内存。
+ `Concurrency`— 上载分段文档的最大并发调用次数。 AWS X-Ray
+ `Region`— 将区段发送到特定区域的 AWS X-Ray 服务。
+ `Socket` - 配置进程守护程序的绑定。
+ `UDPAddress` - 更改进程守护程序侦听的端口。
+ `TCPAddress` - 侦听[对其他 TCP 端口上的 X-Ray 服务的调用](xray-api-sampling.md)。
+ `Logging` - 配置日志记录行为。
+ `LogRotation` - 设置为 `false` 以禁用日志轮换。
+ `LogLevel` - 更改日志级别，依次为从最详细到最不详细：`dev`、`debug`、`info` 或 `prod`、`warn`、`error`、`prod`。默认为 `prod`，等同于 `info`。
+ `LogPath` - 将日志输出到指定文件路径。
+ `LocalMode`— 设置`true`为可跳过对 EC2 实例元数据的检查。
+ `ResourceARN`— 运行守护程序的资源的亚马逊 AWS 资源名称 (ARN)。
+ `RoleARN` - 采用指定的 IAM 角色将分段上传到其他账户。
+ `ProxyAddress`— AWS X-Ray 通过代理将区段上传到。
+ `Endpoint` - 将 X-Ray 服务端点改为进程守护程序向其发送分段文档的节点。
+ `NoVerifySSL` - 禁用 TLS 证书验证。
+ `Version` - 进程守护程序配置文件格式版本。文件格式版本是**必填**字段。
**Example Xray-daemon.yaml**
此配置文件将进程守护程序的侦听端口改为 3000，并且关闭对实例元数据的检查，设置用于上传分段的角色，以及更改区域和日志记录选项。
```
Socket:
UDPAddress: "127.0.0.1:3000"
TCPAddress: "127.0.0.1:3000"
Region: "us-west-2"
Logging:
LogLevel: "warn"
LogPath: "/var/log/xray-daemon.log"
LocalMode: true
RoleARN: "arn:aws:iam::123456789012:role/xray-cross-account"
Version: 2
```
# 在本地运行 X-Ray 进程守护程序
**注意**
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)。
你可以在 Linux、macOS、Windows 或 Docker 容器中本地运行 AWS X-Ray 守护程序。当您在开发和测试经过检测的应用程序时，运行进程守护程序可将跟踪数据中继到 X-Ray。使用[此处](xray-daemon.md#xray-daemon-downloading)的说明下载并解压缩进程守护程序。
在本地运行时，守护程序可以从 AWS SDK 凭据文件（`.aws/credentials`在您的用户目录中）或环境变量中读取凭据。有关更多信息，请参阅 [授予进程守护程序向 X-Ray 发送数据的权限](xray-daemon.md#xray-daemon-permissions)。
进程守护程序在端口 2000 上侦听 UDP 数据。您可以使用配置文件和命令行选项更改端口和其他选项。有关更多信息，请参阅 [配置 AWS X-Ray 守护程序](xray-daemon-configuration.md)。
## 在 Linux 上运行 X-Ray 进程守护程序
您可以从命令行运行进程守护程序可执行文件。使用 `-o` 选项以本地模式运行，`-n` 选项设置区域。
```
~/xray-daemon$ ./xray -o -n us-east-2
```
要在后台运行进程守护程序，请使用 `&`。
```
~/xray-daemon$ ./xray -o -n us-east-2 &
```
使用 `pkill` 终止在后台运行的进程守护程序进程。
```
~$ pkill xray
```
## 在 Docker 容器中运行 X-Ray 进程守护程序
要在 Docker 容器中本地运行进程守护程序，请将以下文本保存为名为 `Dockerfile` 的文件。在 Amazon ECR 上下载完整的[示例映像](https://gallery.ecr.aws/xray/aws-xray-daemon)。有关更多信息，请参阅[下载进程守护程序](xray-daemon.md#xray-daemon-downloading)。
**Example Dockerfile — Amazon Linux**
```
FROM amazonlinux
RUN yum install -y unzip
RUN curl -o daemon.zip https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zip
RUN unzip daemon.zip && cp xray /usr/bin/xray
ENTRYPOINT ["/usr/bin/xray", "-t", "0.0.0.0:2000", "-b", "0.0.0.0:2000"]
EXPOSE 2000/udp
EXPOSE 2000/tcp
```
利用 `docker build` 构建容器映像。
```
~/xray-daemon$ docker build -t xray-daemon .
```
利用 `docker run` 在容器中运行映像。
```
~/xray-daemon$ docker run \
--attach STDOUT \
-v ~/.aws/:/root/.aws/:ro \
--net=host \
-e AWS_REGION=us-east-2 \
--name xray-daemon \
-p 2000:2000/udp \
xray-daemon -o
```
此命令使用以下选项：
+ `--attach STDOUT` - 在终端查看进程守护程序的输出。
+ `-v ~/.aws/:/root/.aws/:ro`— 授予容器对`.aws`目录的只读访问权限，使其能够读取您的 AWS SDK 凭据。
+ `AWS_REGION=us-east-2` - 设置 `AWS_REGION` 环境变量，以通知进程守护程序使用哪个区域。
+ `--net=host` - 将容器附加到 `host` 网络。主机网络上的容器无需发布端口即可互相通信。
+ `-p 2000:2000/udp` - 将您计算机上的 UDP 端口 2000 映射到容器上的同一端口。对于同一网络中的容器进行通信而言，这不是必需的，但它允许您[通过命令行](xray-api-sendingdata.md#xray-api-daemon)或通过未在 Docker 中运行的应用程序将分段发送到进程守护程序。
+ `--name xray-daemon` - 命名容器 `xray-daemon`，而不是随机生成名称。
+ `-o`（位于映像名称后） - 将 `-o` 选项追加到入口点（在容器中运行进程守护程序）。此选项告诉守护程序在本地模式下运行，以防止它尝试读取 Amazon EC2 实例元数据。
要停止进程守护程序，请使用 `docker stop`。如果您更改 `Dockerfile` 并生成新映像，需要删除现有容器，然后才能创建另一个具有相同名称的容器。使用 `docker rm` 删除容器。
```
$ docker stop xray-daemon
$ docker rm xray-daemon
```
## 在 Windows 上运行 X-Ray 进程守护程序
您可以从命令行运行进程守护程序可执行文件。使用 `-o` 选项以本地模式运行，`-n` 选项设置区域。
```
> .\xray_windows.exe -o -n us-east-2
```
使用 PowerShell 脚本为守护程序创建和运行服务。
**Example PowerShell 脚本-Windows**
```
if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ){
sc.exe stop AWSXRayDaemon
sc.exe delete AWSXRayDaemon
}
if ( Get-Item -path aws-xray-daemon -ErrorAction SilentlyContinue ) {
Remove-Item -Recurse -Force aws-xray-daemon
}
$currentLocation = Get-Location
$zipFileName = "aws-xray-daemon-windows-service-3.x.zip"
$zipPath = "$currentLocation\$zipFileName"
$destPath = "$currentLocation\aws-xray-daemon"
$daemonPath = "$destPath\xray.exe"
$daemonLogPath = "C:\inetpub\wwwroot\xray-daemon.log"
$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPath
Add-Type -Assembly "System.IO.Compression.Filesystem"
[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
sc.exe create AWSXRayDaemon binPath= "$daemonPath -f $daemonLogPath"
sc.exe start AWSXRayDaemon
```
## 在 OS X 上运行 X-Ray 进程守护程序
您可以从命令行运行进程守护程序可执行文件。使用 `-o` 选项以本地模式运行，`-n` 选项设置区域。
```
~/xray-daemon$ ./xray_mac -o -n us-east-2
```
要在后台运行进程守护程序，请使用 `&`。
```
~/xray-daemon$ ./xray_mac -o -n us-east-2 &
```
使用 `nohup` 可防止在终端关闭时终止进程守护程序。
```
~/xray-daemon$ nohup ./xray_mac &
```
# 正在运行 X-Ray 守护程序 AWS Elastic Beanstalk
**注意**
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 X-Ray，您可以在 Elastic Beanstalk 环境的 Amazon EC2 实例上运行 X-Ray 守护程序。有关受支持平台的列表，请参阅 *AWS Elastic Beanstalk 开发人员指南*中的[配置 AWS X-Ray 调试](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environment-configuration-debugging.html)。
**注意**
该进程守护程序使用环境的实例配置文件获取权限。有关将权限添加到 Elastic Beanstalk 实例配置文件的说明，请参阅[授予进程守护程序向 X-Ray 发送数据的权限](xray-daemon.md#xray-daemon-permissions)。
Elastic Beanstalk 平台提供配置选项，您可以设置它，自动运行进程守护程序。您可以在源代码的配置文件中启用进程守护程序，或者通过在 Elastic Beanstalk 控制台中选择选项来启用。启用配置选项后，进程守护程序将安装到实例上，并作为服务运行。
Elastic Beanstalk 平台上包括的版本可能不是最新版本。请参阅[支持的平台主题](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/concepts.platforms.html)，找出您的平台配置适用的进程守护程序版本。
Elastic Beanstalk 在多容器 Docker (Amazon ECS) 平台上不提供 X-Ray 进程守护程序。
## 使用 Elastic Beanstalk X-Ray 集成运行 X-Ray 进程守护程序
使用控制台启用 X-Ray 集成，或者在应用程序源代码中使用配置文件来配置。
**在 Elastic Beanstalk 控制台中启用 X-Ray 进程守护程序**
1. 打开 [Elastic Beanstalk 控制台](https://console.aws.amazon.com/elasticbeanstalk)。
1. 导航到您的环境的[管理控制台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)。
1. 选择**配置**。
1. 选择**软件设置**。
1. 对于 **X-Ray 进程守护程序**，选择**已启动**。
1. 选择**应用**。
您可以在源代码中包含配置文件，使得您的配置可以在环境之间移植。
**Example .ebextensions/xray-daemon.config**
```
option_settings:
aws:elasticbeanstalk:xray:
XRayEnabled: true
```
Elastic Beanstalk 将配置文件传递到进程守护程序并将日志输出到标准位置。
**在 Windows Server 平台上**
+ **配置文件** - `C:\Program Files\Amazon\XRay\cfg.yaml`
+ **日志** - `c:\Program Files\Amazon\XRay\logs\xray-service.log`
**在 Linux 平台上**
+ **配置文件** - `/etc/amazon/xray/cfg.yaml`
+ **日志** - `/var/log/xray/xray.log`
Elastic Beanstalk 提供了用于从或命令行提取实例日志 AWS 管理控制台 的工具。您可以使用配置文件添加一项任务，来指示 Elastic Beanstalk 包含 X-Ray 进程守护程序日志。
**Example .ebextensions/xray-logs.config - Linux**
```
files:
"/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" :
mode: "000644"
owner: root
group: root
content: |
/var/log/xray/xray.log
```
**Example .ebextensions/xray-logs.config - Windows Server**
```
files:
"c:/Program Files/Amazon/ElasticBeanstalk/config/taillogs.d/xray-daemon.conf" :
mode: "000644"
owner: root
group: root
content: |
c:\Progam Files\Amazon\XRay\logs\xray-service.log
```
有关更多信息，请参阅 *AWS Elastic Beanstalk 开发人员指南*中的[查看来自 Elastic Beanstalk 环境的 Amazon EC2 实例日志](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.logging.html)。
## 手动下载和运行 X-Ray 进程守护程序（高级）
如果 X-Ray 进程守护程序对您的平台配置不可用，则可以从 Amazon S3 下载它并使用配置文件来运行。
使用 Elastic Beanstalk 配置文件下载并运行进程守护程序。
**Example .ebextensions/xray.config - Linux**
```
commands:
01-stop-tracing:
command: yum remove -y xray
ignoreErrors: true
02-copy-tracing:
command: 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
03-start-tracing:
command: yum install -y /home/ec2-user/xray.rpm
files:
"/opt/elasticbeanstalk/tasks/taillogs.d/xray-daemon.conf" :
mode: "000644"
owner: root
group: root
content: |
/var/log/xray/xray.log
"/etc/amazon/xray/cfg.yaml" :
mode: "000644"
owner: root
group: root
content: |
Logging:
LogLevel: "debug"
Version: 2
```
**Example .ebextensions/xray.config - Windows Server**
```
container_commands:
01-execute-config-script:
command: Powershell.exe -ExecutionPolicy Bypass -File c:\\temp\\installDaemon.ps1
waitAfterCompletion: 0
files:
"c:/temp/installDaemon.ps1":
content: |
if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ) {
sc.exe stop AWSXRayDaemon
sc.exe delete AWSXRayDaemon
}
$targetLocation = "C:\Program Files\Amazon\XRay"
if ((Test-Path $targetLocation) -eq 0) {
mkdir $targetLocation
}
$zipFileName = "aws-xray-daemon-windows-service-3.x.zip"
$zipPath = "$targetLocation\$zipFileName"
$destPath = "$targetLocation\aws-xray-daemon"
if ((Test-Path $destPath) -eq 1) {
Remove-Item -Recurse -Force $destPath
}
$daemonPath = "$destPath\xray.exe"
$daemonLogPath = "$targetLocation\xray-daemon.log"
$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPath
Add-Type -Assembly "System.IO.Compression.Filesystem"
[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
New-Service -Name "AWSXRayDaemon" -StartupType Automatic -BinaryPathName "`"$daemonPath`" -f `"$daemonLogPath`""
sc.exe start AWSXRayDaemon
encoding: plain
"c:/Program Files/Amazon/ElasticBeanstalk/config/taillogs.d/xray-daemon.conf" :
mode: "000644"
owner: root
group: root
content: |
C:\Program Files\Amazon\XRay\xray-daemon.log
```
这些示例还将进程守护程序日志文件添加到了 Elastic Beanstalk 的尾日志任务，以在您通过控制台或 Elastic Beanstalk 命令行界面 (EB CLI) 请求日志时将其包含在内。
# 在亚马逊上运行 X-Ray 守护程序 EC2
**注意**
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)。
您可以在亚马逊 EC2的以下操作系统上运行 X-Ray 守护程序：
+ Amazon Linux
+ Ubuntu
+ Windows Server（2012 R2 及更高版本）
使用实例配置文件授予进程守护程序权限以上传跟踪数据到 X-Ray。有关更多信息，请参阅 [授予进程守护程序向 X-Ray 发送数据的权限](xray-daemon.md#xray-daemon-permissions)。
使用用户数据脚本在启动实例时自动运行进程守护程序。
**Example 用户数据脚本 - Linux**
```
#!/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
```
**Example 用户数据脚本 - Windows Server**
```
if ( Get-Service "AWSXRayDaemon" -ErrorAction SilentlyContinue ) {
sc.exe stop AWSXRayDaemon
sc.exe delete AWSXRayDaemon
}
$targetLocation = "C:\Program Files\Amazon\XRay"
if ((Test-Path $targetLocation) -eq 0) {
mkdir $targetLocation
}
$zipFileName = "aws-xray-daemon-windows-service-3.x.zip"
$zipPath = "$targetLocation\$zipFileName"
$destPath = "$targetLocation\aws-xray-daemon"
if ((Test-Path $destPath) -eq 1) {
Remove-Item -Recurse -Force $destPath
}
$daemonPath = "$destPath\xray.exe"
$daemonLogPath = "$targetLocation\xray-daemon.log"
$url = "https://s3.dualstack.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-windows-service-3.x.zip"
Invoke-WebRequest -Uri $url -OutFile $zipPath
Add-Type -Assembly "System.IO.Compression.Filesystem"
[io.compression.zipfile]::ExtractToDirectory($zipPath, $destPath)
New-Service -Name "AWSXRayDaemon" -StartupType Automatic -BinaryPathName "`"$daemonPath`" -f `"$daemonLogPath`""
sc.exe start AWSXRayDaemon
```
# 在 Amazon ECS 上运行 X-Ray 进程守护程序
**注意**
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)。
在 Amazon ECS 上，创建运行 X-Ray 进程守护程序的 Docker 映像，将其上传到 Docker 映像存储库，然后部署到 Amazon ECS 集群。您可以在任务定义文件中使用端口映射和网络模式设置，允许您的应用程序与进程守护程序容器通信。
## 使用官方 Docker 映像
X-Ray 在 Amazon ECR 上提供了 Docker[ 容器映像](https://gallery.ecr.aws/xray/aws-xray-daemon)，您可以与您的应用程序一起部署该映像。有关更多信息，请参阅[下载进程守护程序](xray-daemon.md#xray-daemon-downloading)。
**Example 任务定义**
```
{
"name": "xray-daemon",
"image": "amazon/aws-xray-daemon",
"cpu": 32,
"memoryReservation": 256,
"portMappings" : [
{
"hostPort": 0,
"containerPort": 2000,
"protocol": "udp"
}
]
}
```
## 创建和构建 Docker 映像
对于自定义配置，您可能需要定义自己的 Docker 映像。
为任务角色添加托管式策略，授予进程守护程序将跟踪数据上传到 X-Ray 的权限。有关更多信息，请参阅 [授予进程守护程序向 X-Ray 发送数据的权限](xray-daemon.md#xray-daemon-permissions)。
使用以下 Dockerfile 之一来创建运行进程守护程序的映像。
**Example Dockerfile — Amazon Linux**
```
FROM amazonlinux
RUN yum install -y unzip
RUN curl -o daemon.zip https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-linux-3.x.zip
RUN unzip daemon.zip && cp xray /usr/bin/xray
ENTRYPOINT ["/usr/bin/xray", "-t", "0.0.0.0:2000", "-b", "0.0.0.0:2000"]
EXPOSE 2000/udp
EXPOSE 2000/tcp
```
**注意**
需要 `-t` 和 `-b` 来指定绑定地址侦听多容器环境的环回。
**Example Dockerfile - Ubuntu**
对于 Debian 衍生物，您还需要安装证书颁发机构 (CA) 证书，以避免下载安装程序时遇到问题。
```
FROM ubuntu:16.04
RUN apt-get update && apt-get install -y --force-yes --no-install-recommends apt-transport-https curl ca-certificates wget && apt-get clean && apt-get autoremove && rm -rf /var/lib/apt/lists/*
RUN wget https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.deb
RUN dpkg -i aws-xray-daemon-3.x.deb
ENTRYPOINT ["/usr/bin/xray", "--bind=0.0.0.0:2000", "--bind-tcp=0.0.0.0:2000"]
EXPOSE 2000/udp
EXPOSE 2000/tcp
```
在您的任务定义中，配置取决于您使用的联网模式。桥式联网是默认模式，可在您的默认 VPC 中使用。在桥式网络中，将 `AWS_XRAY_DAEMON_ADDRESS` 环境变量设置为告诉 X-Ray 开发工具包引用哪个容器端口并设置主机端口。例如，可以发布 UDP 端口 2000，并创建您的应用程序容器与进程守护程序容器之间的链接。
**Example 任务定义**
```
{
"name": "xray-daemon",
"image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon",
"cpu": 32,
"memoryReservation": 256,
"portMappings" : [
{
"hostPort": 0,
"containerPort": 2000,
"protocol": "udp"
}
]
},
{
"name": "scorekeep-api",
"image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api",
"cpu": 192,
"memoryReservation": 512,
"environment": [
{ "name" : "AWS_REGION", "value" : "us-east-2" },
{ "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" },
{ "name" : "AWS_XRAY_DAEMON_ADDRESS", "value" : "xray-daemon:2000" }
],
"portMappings" : [
{
"hostPort": 5000,
"containerPort": 5000
}
],
"links": [
"xray-daemon"
]
}
```
如果您在 VPC 的私有子网中运行集群，可以使用 [`awsvpc` 网络模式](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html)将弹性网络接口 (ENI) 附加到您的容器。这样可以避免使用链接。省略端口映射、链接和 `AWS_XRAY_DAEMON_ADDRESS` 环境变量中的主机端口。
**Example VPC 任务定义**
```
{
"family": "scorekeep",
"networkMode":"awsvpc",
"containerDefinitions": [
{
"name": "xray-daemon",
"image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/xray-daemon",
"cpu": 32,
"memoryReservation": 256,
"portMappings" : [
{
"containerPort": 2000,
"protocol": "udp"
}
]
},
{
"name": "scorekeep-api",
"image": "123456789012.dkr.ecr.us-east-2.amazonaws.com/scorekeep-api",
"cpu": 192,
"memoryReservation": 512,
"environment": [
{ "name" : "AWS_REGION", "value" : "us-east-2" },
{ "name" : "NOTIFICATION_TOPIC", "value" : "arn:aws:sns:us-east-2:123456789012:scorekeep-notifications" }
],
"portMappings" : [
{
"containerPort": 5000
}
]
}
]
}
```
## 在 Amazon ECS 控制台中配置命令行选项
命令行选项将覆盖映像配置文件中的任何冲突值。命令行选项通常用于本地测试，但为了方便设置环境变量或控制启动过程，也可以使用命令行选项。
添加命令行选项会更新传递到该容器的 Docker `CMD`。有关更多信息，请参阅 [Docker 运行参考](https://docs.docker.com/engine/reference/run/#overriding-dockerfile-image-defaults)。
**设置命令行选项**
1. 打开 Amazon ECS 经典控制台，网址为[https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/)。
1. 从导航栏中，选择包含您的任务定义的区域。
1. 在导航窗格中，选择 **Task Definitions**。
1. 在 **Task Definitions** 页面上，选择要修订的任务定义左侧的框，然后选择 **Create new revision**。
1. 在**创建任务定义新修订**页面上，选择该容器。
1. 在**环境**部分，将用逗号分隔的命令行选项列表添加到**命令**字段。
1. 选择**更新**。
1. 验证信息并选择 **Create**。
以下示例演示了如何为 `RoleARN` 选项编写以逗号分隔的命令行选项。`RoleARN` 选项采用指定的 IAM 角色将分段上传到其他账户。
**Example**
```
--role-arn, arn:aws:iam::123456789012:role/xray-cross-account
```
要了解有关 X-Ray 中可用命令行选项的更多信息，请参阅[配置 AWS X-Ray 守护程序](xray-daemon-configuration.md)。