本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 設定 AWS X-Ray 協助程式
**注意**
X-Ray 開發套件/協助程式維護通知 – 在 2026 年 2 月 25 日， AWS X-Ray SDKs/協助程式將進入維護模式，其中 AWS 將限制 X-Ray 開發套件和協助程式版本，以僅解決安全問題。如需支援時間軸的詳細資訊，請參閱 [X-Ray SDK 和協助程式支援時間表](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、rror、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 資源的 Amazon Resource Name (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 資源的 Amazon Resource Name (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
```