本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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)。
**注意**
您現在可以使用 CloudWatch 代理程式，從 Amazon EC2 執行個體和內部部署伺服器收集指標、日誌和追蹤。CloudWatch 代理程式 1.300025.0 版及更新版本可以從 [OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel) 或 [X-Ray](xray-instrumenting-your-app.md#xray-instrumenting-xray-sdk) 用戶端 SDKs 收集追蹤，並將其傳送至 X-Ray。使用 CloudWatch 代理程式而非 AWS Distro for OpenTelemetry (ADOT) 收集器或 X-Ray 協助程式來收集追蹤，可協助您減少管理的代理程式數量。如需詳細資訊，請參閱 [CloudWatch 使用者指南中的 CloudWatch 代理程式](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)主題。 CloudWatch
AWS X-Ray 協助程式是一種軟體應用程式，可接聽 UDP 連接埠 2000 上的流量、收集原始區段資料，並將其轉送至 AWS X-Ray API。協助程式可與 AWS X-Ray SDKs 搭配使用，且必須執行，以便 SDKs 傳送的資料可以到達 X-Ray 服務。X-Ray 協助程式是開放原始碼專案。您可以在 GitHub 上關注專案並提交問題和提取 (pull) 請求：[github.com/aws/aws-xray-daemon](https://github.com/aws/aws-xray-daemon)
在 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)([sig](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
```
先前或 Alpha 版本可以透過將 取代`3.x`為 `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`為所需的版本來發行。
------
## 驗證精靈存檔的簽章
GPG 簽章檔案會針對以 ZIP 存檔形式壓縮的精靈資產包含在其中。公有金鑰位於此處：[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. 將公開金鑰匯入至您的 keyring。
```
$ 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** – [在 Amazon EC2 上執行 X-Ray 協助程式](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 EC2 上，協助程式會自動使用執行個體的執行個體描述檔角色。如需在本機執行協助程式所需的登入資料資訊，請參閱在[本機執行您的應用程式](security_iam_service-with-iam.md#xray-permissions-local)。
若您在超過一個位置指定登入資料 (登入資料檔案、執行個體描述檔，或是環境變數)，軟體開發套件提供者鏈會判斷使用的登入資料有哪些。如需提供登入資料給 SDK 的詳細資訊，請參閱《適用於 *AWS Go 的 SDK 開發人員指南*》中的[指定登入](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 開發套件/協助程式維護通知 – 在 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
```
# 在本機執行 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)。
您可以在 Linux、MacOS、Windows AWS X-Ray 或 Docker 容器中於本機執行協助程式。當您開發和測試檢測應用程式時，執行協助程式將追蹤資料轉送至 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 開發套件/協助程式維護通知 – 在 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)。
若要將追蹤資料從應用程式轉送至 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. 選擇 **Configuration (組態)**。
1. 選擇 **Software Settings (軟體設定)**。
1. 針對 **X-Ray daemon (X-Ray 精靈)**，請選擇 **Enabled (啟用)**。
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
```
如需詳細資訊，請參閱[《 開發人員指南》中的從 Elastic Beanstalk 環境的 Amazon EC2 執行個體檢視日誌](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.logging.html)。 *AWS Elastic Beanstalk *
## 手動下載並執行 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) 請求日誌時包含該檔案。
# 在 Amazon EC2 上執行 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)。
您可以在 Amazon 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 開發套件/協助程式維護通知 – 在 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)。
在 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)。
使用以下其中一個 Dockerfiles 建立執行精靈的映像。
**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 SDK 要參考和設定主機連接埠的容器連接埠。舉例來說，您可以發佈 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. 在 **Create new revision of Task Definition** (建立任務定義的新修訂版) 頁面上，選取容器。
1. 在 **ENVIRONMENT** (環境) 區段中，將逗號分隔的命令列選項清單新增至 **Command** (命令) 欄位。
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)。