本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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)。