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

# 配置 Amazon X-Ray 守护程序
配置

**注意**  
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)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.amazonaws.cn/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 服务端点的 [Amazon Web Services 区域](https://docs.amazonaws.cn/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`— 运行守护程序的资源的亚马逊 Amazon 资源名称 (ARN)。
+ `-p`，`--proxy-address`— Amazon X-Ray 通过代理将区段上传到。必须指定代理服务器的协议。

  ```
  --proxy-address "http://192.0.2.0:3000"
  ```
+ `-n`、`--region` - 向特定区域中的 X-Ray 服务发送分段。
+ `-v`，`--version`— 显示 Amazon X-Ray 守护程序版本。
+ `-h`、`--help` - 显示帮助屏幕。

## 使用配置文件


您也可以使用 YAML 格式文件来配置进程守护程序。使用 `-c` 选项传递配置文件到进程守护程序。

```
~$ ./xray -c ~/xray-daemon.yaml
```

**配置文件选项**
+ `TotalBufferSizeMB` - 最大缓冲区大小（单位：MB，最小值为 3）。选择 0 则使用 1% 的主机内存。
+ `Concurrency`— 上载分段文档的最大并发调用次数。 Amazon X-Ray 
+ `Region`— 将区段发送到特定区域的 Amazon 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`— 运行守护程序的资源的亚马逊 Amazon 资源名称 (ARN)。
+ `RoleARN` - 采用指定的 IAM 角色将分段上传到其他账户。
+ `ProxyAddress`— Amazon 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
```