# AWS X-Ray daemon
**Note**
X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
**Note**
You can now use the CloudWatch agent to collect metrics, logs and traces from Amazon EC2 instances and on-premise servers. CloudWatch agent version 1.300025.0 and later can collect traces from [OpenTelemetry](xray-instrumenting-your-app.md#xray-instrumenting-opentel) or [X-Ray](xray-instrumenting-your-app.md#xray-instrumenting-xray-sdk) client SDKs, and send them to X-Ray. Using the CloudWatch agent instead of the AWS Distro for OpenTelemetry (ADOT) Collector or X-Ray daemon to collect traces can help you reduce the number of agents that you manage. See the [CloudWatch agent](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html) topic in the CloudWatch User Guide for more information.
The AWS X-Ray daemon is a software application that listens for traffic on UDP port 2000, gathers raw segment data, and relays it to the AWS X-Ray API. The daemon works in conjunction with the AWS X-Ray SDKs and must be running so that data sent by the SDKs can reach the X-Ray service. The X-Ray daemon is an open source project. You can follow the project and submit issues and pull requests on GitHub: [github.com/aws/aws-xray-daemon](https://github.com/aws/aws-xray-daemon)
On AWS Lambda and AWS Elastic Beanstalk, use those services' integration with X-Ray to run the daemon. Lambda runs the daemon automatically any time a function is invoked for a sampled request. On Elastic Beanstalk, [use the `XRayEnabled` configuration option](xray-daemon-beanstalk.md) to run the daemon on the instances in your environment. For more information, see
To run the X-Ray daemon locally, on-premises, or on other AWS services, download it, [run it](#xray-daemon-running), and then [give it permission](#xray-daemon-permissions) to upload segment documents to X-Ray.
## Downloading the daemon
You can download the daemon from Amazon S3, Amazon ECR, or Docker Hub, and then run it locally, or install it on an Amazon EC2 instance on launch.
------
#### [ Amazon S3 ]
**X-Ray daemon installers and executables**
+ **Linux (executable)** – [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 installer)** – [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 installer)** – [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, executable)** – [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 installer)** – [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 installer)** – [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 (executable)** – [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 (executable)** – [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 (service) ** – [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))
These links always point to the latest 3.x release of the daemon. To download a specific release, do the following:
+ If you want to download a release prior to version `3.3.0`, replace `3.x` with the version number. For example, `2.1.0`. Prior to version `3.3.0`, the only available architecture is `arm64`. For example, `2.1.0` and `arm64`.
+ If you want to download a release after version `3.3.0`, replace `3.x` with the version number and `arch` with the architecture type.
X-Ray assets are replicated to buckets in every supported region. To use the bucket closest to you or your AWS resources, replace the region in the above links with your region.
```
https://s3.us-west-2.amazonaws.com/aws-xray-assets.us-west-2/xray-daemon/aws-xray-daemon-3.x.rpm
```
------
#### [ Amazon ECR ]
As of version 3.2.0 the daemon can be found on [Amazon ECR](https://gallery.ecr.aws/xray/aws-xray-daemon). Before pulling an image you should [authenticate your docker client](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html#public-registry-auth) to the Amazon ECR public registry.
Pull the latest released 3.x version tag by running the following command:
```
docker pull public.ecr.aws/xray/aws-xray-daemon:3.x
```
Prior or alpha releases can be downloaded by replacing `3.x` with `alpha` or a specific version number. It is not recommended to use a daemon image with an alpha tag in a production environment.
------
#### [ Docker Hub ]
The daemon can be found on [Docker Hub](https://hub.docker.com/r/amazon/aws-xray-daemon). To download the latest released 3.x version, run the following command:
```
docker pull amazon/aws-xray-daemon:3.x
```
Prior releases of the daemon can be released by replacing `3.x` with the desired version.
------
## Verifying the daemon archive's signature
GPG signature files are included for daemon assets compressed in ZIP archives. The public key is here: [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).
You can use the public key to verify that the daemon's ZIP archive is original and unmodified. First, import the public key with [GnuPG](https://gnupg.org/index.html).
**To import the public key**
1. Download the public key.
```
$ BUCKETURL=https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2
$ wget $BUCKETURL/xray-daemon/aws-xray.gpg
```
1. Import the public key into your 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
```
Use the imported key to verify the signature of the daemon's ZIP archive.
**To verify an archive's signature**
1. Download the archive and signature file.
```
$ 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. Run `gpg --verify` to verify the signature.
```
$ 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
```
Note the warning about trust. A key is only trusted if you or someone you trust has signed it. This does not mean that the signature is invalid, only that you have not verified the public key.
## Running the daemon
Run the daemon locally from the command line. Use the `-o` option to run in local mode, and `-n` to set the region.
```
~/Downloads$ ./xray -o -n us-east-2
```
For detailed platform-specific instructions, see the following topics:
+ **Linux (local)** – [Running the X-Ray daemon on Linux](xray-daemon-local.md#xray-daemon-local-linux)
+ **Windows (local)** – [Running the X-Ray daemon on Windows](xray-daemon-local.md#xray-daemon-local-windows)
+ **Elastic Beanstalk** – [Running the X-Ray daemon on AWS Elastic Beanstalk](xray-daemon-beanstalk.md)
+ **Amazon EC2** – [Running the X-Ray daemon on Amazon EC2](xray-daemon-ec2.md)
+ **Amazon ECS** – [Running the X-Ray daemon on Amazon ECS](xray-daemon-ecs.md)
You can customize the daemon's behavior further by using command line options or a configuration file. See [Configuring the AWS X-Ray daemon](xray-daemon-configuration.md) for details.
## Giving the daemon permission to send data to X-Ray
The X-Ray daemon uses the AWS SDK to upload trace data to X-Ray, and it needs AWS credentials with permission to do that.
On Amazon EC2, the daemon uses the instance's instance profile role automatically. For information about credentials required to run the daemon locally, see [ running your application locally](security_iam_service-with-iam.md#xray-permissions-local).
If you specify credentials in more than one location (credentials file, instance profile, or environment variables), the SDK provider chain determines which credentials are used. For more information about providing credentials to the SDK, see [Specifying Credentials](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/#specifying-credentials) in the *AWS SDK for Go Developer Guide*.
The IAM role or user that the daemon's credentials belong to must have permission to write data to the service on your behalf.
+ To use the daemon on Amazon EC2, create a new instance profile role or add the managed policy to an existing one.
+ To use the daemon on Elastic Beanstalk, add the managed policy to the Elastic Beanstalk default instance profile role.
+ To run the daemon locally, see [running your application locally](security_iam_service-with-iam.md#xray-permissions-local).
For more information, see [Identity and access management for AWS X-Ray](security-iam.md).
## X-Ray daemon logs
The daemon outputs information about its current configuration and segments that it sends to 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)
```
By default, the daemon outputs logs to STDOUT. If you run the daemon in the background, use the `--log-file` command line option or a configuration file to set the log file path. You can also set the log level and disable log rotation. See [Configuring the AWS X-Ray daemon](xray-daemon-configuration.md) for instructions.
On Elastic Beanstalk, the platform sets the location of the daemon logs. See [Running the X-Ray daemon on AWS Elastic Beanstalk](xray-daemon-beanstalk.md) for details.
# Configuring the AWS X-Ray daemon
**Note**
X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
You can use command line options or a configuration file to customize the X-Ray daemon's behavior. Most options are available using both methods, but some are only available in configuration files and some only at the command line.
To get started, the only option that you need to know is `-n` or `--region`, which you use to set the region that the daemon uses to send trace data to X-Ray.
```
~/xray-daemon$ ./xray -n us-east-2
```
If you are running the daemon locally, that is, not on Amazon EC2, you can add the `-o` option to skip checking for instance profile credentials so the daemon will become ready more quickly.
```
~/xray-daemon$ ./xray -o -n us-east-2
```
The rest of the command line options let you configure logging, listen on a different port, limit the amount of memory that the daemon can use, or assume a role to send trace data to a different account.
You can pass a configuration file to the daemon to access advanced configuration options and do things like limit the number of concurrent calls to X-Ray, disable log rotation, and send traffic to a proxy.
**Topics**
+ [Supported environment variables](#xray-daemon-configuration-variables)
+ [Using command line options](#xray-daemon-configuration-commandline)
+ [Using a configuration file](#xray-daemon-configuration-configfile)
## Supported environment variables
The X-Ray daemon supports the following environment variables:
+ `AWS_REGION` – Specifies the [AWS Region](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html#cli-quick-configuration-region) of the X-Ray service endpoint.
+ `HTTPS_PROXY` – Specifies a proxy address for the daemon to upload segments through. This can be either the DNS domain names or IP addresses and port numbers used by your proxy servers.
## Using command line options
Pass these options to the daemon when you run it locally or with a user data script.
**Command Line Options**
+ `-b`, `--bind` – Listen for segment documents on a different UDP port.
```
--bind "127.0.0.1:3000"
```
Default – `2000`.
+ `-t`, `--bind-tcp` – Listen for calls to the X-Ray service on a different TCP port.
```
-bind-tcp "127.0.0.1:3000"
```
Default – `2000`.
+ `-c`, `--config` – Load a configuration file from the specified path.
```
--config "/home/ec2-user/xray-daemon.yaml"
```
+ `-f`, `--log-file` – Output logs to the specified file path.
```
--log-file "/var/log/xray-daemon.log"
```
+ `-l`, `--log-level` – Log level, from most verbose to least: dev, debug, info, warn, error, prod.
```
--log-level warn
```
Default – `prod`
+ `-m`, `--buffer-memory` – Change the amount of memory in MB that buffers can use (minimum 3).
```
--buffer-memory 50
```
Default – 1% of available memory.
+ `-o`, `--local-mode` – Don't check for EC2 instance metadata.
+ `-r`, `--role-arn` – Assume the specified IAM role to upload segments to a different account.
```
--role-arn "arn:aws:iam::123456789012:role/xray-cross-account"
```
+ `-a`, `--resource-arn` – Amazon Resource Name (ARN) of the AWS resource running the daemon.
+ `-p`, `--proxy-address` – Upload segments to AWS X-Ray through a proxy. The proxy server's protocol must be specified.
```
--proxy-address "http://192.0.2.0:3000"
```
+ `-n`, `--region` – Send segments to X-Ray service in a specific region.
+ `-v`, `--version` – Show AWS X-Ray daemon version.
+ `-h`, `--help` – Show the help screen.
## Using a configuration file
You can also use a YAML format file to configure the daemon. Pass the configuration file to the daemon by using the `-c` option.
```
~$ ./xray -c ~/xray-daemon.yaml
```
**Configuration file options**
+ `TotalBufferSizeMB` – Maximum buffer size in MB (minimum 3). Choose 0 to use 1% of host memory.
+ `Concurrency` – Maximum number of concurrent calls to AWS X-Ray to upload segment documents.
+ `Region` – Send segments to AWS X-Ray service in a specific region.
+ `Socket` – Configure the daemon's binding.
+ `UDPAddress` – Change the port on which the daemon listens.
+ `TCPAddress` – Listen for [calls to the X-Ray service](xray-api-sampling.md) on a different TCP port.
+ `Logging` – Configure logging behavior.
+ `LogRotation` – Set to `false` to disable log rotation.
+ `LogLevel` – Change the log level, from most verbose to least: `dev`, `debug`, `info` or `prod`, `warn`, `error`, `prod`. The default is `prod`, which is equivalent to `info`.
+ `LogPath` – Output logs to the specified file path.
+ `LocalMode` – Set to `true` to skip checking for EC2 instance metadata.
+ `ResourceARN` – Amazon Resource Name (ARN) of the AWS resource running the daemon.
+ `RoleARN` – Assume the specified IAM role to upload segments to a different account.
+ `ProxyAddress` – Upload segments to AWS X-Ray through a proxy.
+ `Endpoint` – Change the X-Ray service endpoint to which the daemon sends segment documents.
+ `NoVerifySSL` – Disable TLS certificate verification.
+ `Version` – Daemon configuration file format version. The file format version is a **required** field.
**Example Xray-daemon.yaml**
This configuration file changes the daemon's listening port to 3000, turns off checks for instance metadata, sets a role to use for uploading segments, and changes region and logging options.
```
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
```
# Running the X-Ray daemon locally
**Note**
X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
You can run the AWS X-Ray daemon locally on Linux, MacOS, Windows, or in a Docker container. Run the daemon to relay trace data to X-Ray when you are developing and testing your instrumented application. Download and extract the daemon by using the instructions [here](xray-daemon.md#xray-daemon-downloading).
When running locally, the daemon can read credentials from an AWS SDK credentials file (`.aws/credentials` in your user directory) or from environment variables. For more information, see [Giving the daemon permission to send data to X-Ray](xray-daemon.md#xray-daemon-permissions).
The daemon listens for UDP data on port 2000. You can change the port and other options by using a configuration file and command line options. For more information, see [Configuring the AWS X-Ray daemon](xray-daemon-configuration.md).
## Running the X-Ray daemon on Linux
You can run the daemon executable from the command line. Use the `-o` option to run in local mode, and `-n` to set the region.
```
~/xray-daemon$ ./xray -o -n us-east-2
```
To run the daemon in the background, use `&`.
```
~/xray-daemon$ ./xray -o -n us-east-2 &
```
Terminate a daemon process running in the background with `pkill`.
```
~$ pkill xray
```
## Running the X-Ray daemon in a Docker container
To run the daemon locally in a Docker container, save the following text to a file named `Dockerfile`. Download the complete [example image](https://gallery.ecr.aws/xray/aws-xray-daemon) on Amazon ECR. See [downloading the daemon](xray-daemon.md#xray-daemon-downloading) for more information.
**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
```
Build the container image with `docker build`.
```
~/xray-daemon$ docker build -t xray-daemon .
```
Run the image in a container with `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
```
This command uses the following options:
+ `--attach STDOUT` – View output from the daemon in the terminal.
+ `-v ~/.aws/:/root/.aws/:ro` – Give the container read-only access to the `.aws` directory to let it read your AWS SDK credentials.
+ `AWS_REGION=us-east-2` – Set the `AWS_REGION` environment variable to tell the daemon which region to use.
+ `--net=host` – Attach the container to the `host` network. Containers on the host network can communicate with each other without publishing ports.
+ `-p 2000:2000/udp` – Map UDP port 2000 on your machine to the same port on the container. This is not required for containers on the same network to communicate, but it does let you send segments to the daemon [from the command line](xray-api-sendingdata.md#xray-api-daemon) or from an application not running in Docker.
+ `--name xray-daemon` – Name the container `xray-daemon` instead of generating a random name.
+ `-o` (after the image name) – Append the `-o` option to the entry point that runs the daemon within the container. This option tells the daemon to run in local mode to prevent it from trying to read Amazon EC2 instance metadata.
To stop the daemon, use `docker stop`. If you make changes to the `Dockerfile` and build a new image, you need to delete the existing container before you can create another one with the same name. Use `docker rm` to delete the container.
```
$ docker stop xray-daemon
$ docker rm xray-daemon
```
## Running the X-Ray daemon on Windows
You can run the daemon executable from the command line. Use the `-o` option to run in local mode, and `-n` to set the region.
```
> .\xray_windows.exe -o -n us-east-2
```
Use a PowerShell script to create and run a service for the daemon.
**Example PowerShell script - 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
```
## Running the X-Ray daemon on OS X
You can run the daemon executable from the command line. Use the `-o` option to run in local mode, and `-n` to set the region.
```
~/xray-daemon$ ./xray_mac -o -n us-east-2
```
To run the daemon in the background, use `&`.
```
~/xray-daemon$ ./xray_mac -o -n us-east-2 &
```
Use `nohup` to prevent the daemon from terminating when the terminal is closed.
```
~/xray-daemon$ nohup ./xray_mac &
```
# Running the X-Ray daemon on AWS Elastic Beanstalk
**Note**
X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
To relay trace data from your application to AWS X-Ray, you can run the X-Ray daemon on your Elastic Beanstalk environment's Amazon EC2 instances. For a list of supported platforms, see [Configuring AWS X-Ray Debugging](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environment-configuration-debugging.html) in the *AWS Elastic Beanstalk Developer Guide*.
**Note**
The daemon uses your environment's instance profile for permissions. For instructions about adding permissions to the Elastic Beanstalk instance profile, see [Giving the daemon permission to send data to X-Ray](xray-daemon.md#xray-daemon-permissions).
Elastic Beanstalk platforms provide a configuration option that you can set to run the daemon automatically. You can enable the daemon in a configuration file in your source code or by choosing an option in the Elastic Beanstalk console. When you enable the configuration option, the daemon is installed on the instance and runs as a service.
The version included on Elastic Beanstalk platforms might not be the latest version. See the [Supported Platforms topic](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/concepts.platforms.html) to find out the version of the daemon that is available for your platform configuration.
Elastic Beanstalk does not provide the X-Ray daemon on the Multicontainer Docker (Amazon ECS) platform.
## Using the Elastic Beanstalk X-Ray integration to run the X-Ray daemon
Use the console to turn on X-Ray integration, or configure it in your application source code with a configuration file.
**To enable the X-Ray daemon in the Elastic Beanstalk console**
1. Open the [Elastic Beanstalk console](https://console.aws.amazon.com/elasticbeanstalk).
1. Navigate to the [management console](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html) for your environment.
1. Choose **Configuration**.
1. Choose **Software Settings**.
1. For **X-Ray daemon**, choose **Enabled**.
1. Choose **Apply**.
You can include a configuration file in your source code to make your configuration portable between environments.
**Example .ebextensions/xray-daemon.config**
```
option_settings:
aws:elasticbeanstalk:xray:
XRayEnabled: true
```
Elastic Beanstalk passes a configuration file to the daemon and outputs logs to a standard location.
**On Windows Server Platforms**
+ **Configuration file** – `C:\Program Files\Amazon\XRay\cfg.yaml`
+ **Logs** – `c:\Program Files\Amazon\XRay\logs\xray-service.log`
**On Linux Platforms**
+ **Configuration file** – `/etc/amazon/xray/cfg.yaml`
+ **Logs** – `/var/log/xray/xray.log`
Elastic Beanstalk provides tools for pulling instance logs from the AWS Management Console or command line. You can tell Elastic Beanstalk to include the X-Ray daemon logs by adding a task with a configuration file.
**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
```
See [Viewing Logs from Your Elastic Beanstalk Environment's Amazon EC2 Instances](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/using-features.logging.html) in the *AWS Elastic Beanstalk Developer Guide* for more information.
## Downloading and running the X-Ray daemon manually (advanced)
If the X-Ray daemon isn't available for your platform configuration, you can download it from Amazon S3 and run it with a configuration file.
Use an Elastic Beanstalk configuration file to download and run the daemon.
**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
```
These examples also add the daemon's log file to the Elastic Beanstalk tail logs task, so that it's included when you request logs with the console or Elastic Beanstalk Command Line Interface (EB CLI).
# Running the X-Ray daemon on Amazon EC2
**Note**
X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
You can run the X-Ray daemon on the following operating systems on Amazon EC2:
+ Amazon Linux
+ Ubuntu
+ Windows Server (2012 R2 and newer)
Use an instance profile to grant the daemon permission to upload trace data to X-Ray. For more information, see [Giving the daemon permission to send data to X-Ray](xray-daemon.md#xray-daemon-permissions).
Use a user data script to run the daemon automatically when you launch the instance.
**Example User data script - 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 User data script - 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
```
# Running the X-Ray daemon on Amazon ECS
**Note**
X-Ray SDK/Daemon Maintenance Notice – On February 25th, 2026, the AWS X-Ray SDKs/Daemon will enter maintenance mode, where AWS will limit X-Ray SDK and Daemon releases to address security issues only. For more information on the support timeline, see [X-Ray SDK and Daemon Support timeline](xray-sdk-daemon-timeline.md). We recommend to migrate to OpenTelemetry. For more information on migrating to OpenTelemetry, see [Migrating from X-Ray instrumentation to OpenTelemetry instrumentation ](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html).
In Amazon ECS, create a Docker image that runs the X-Ray daemon, upload it to a Docker image repository, and then deploy it to your Amazon ECS cluster. You can use port mappings and network mode settings in your task definition file to allow your application to communicate with the daemon container.
## Using the official Docker image
X-Ray provides a Docker [container image](https://gallery.ecr.aws/xray/aws-xray-daemon) on Amazon ECR that you can deploy alongside your application. See [downloading the daemon](xray-daemon.md#xray-daemon-downloading) for more information.
**Example Task definition**
```
{
"name": "xray-daemon",
"image": "amazon/aws-xray-daemon",
"cpu": 32,
"memoryReservation": 256,
"portMappings" : [
{
"hostPort": 0,
"containerPort": 2000,
"protocol": "udp"
}
]
}
```
## Create and build a Docker image
For custom configuration, you may need to define your own Docker image.
Add managed policies to your task role to grant the daemon permission to upload trace data to X-Ray. For more information, see [Giving the daemon permission to send data to X-Ray](xray-daemon.md#xray-daemon-permissions).
Use one of the following Dockerfiles to create an image that runs the daemon.
**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
```
**Note**
Flags `-t` and `-b` are required to specify a binding address to listen to the loopback of a multi-container environment.
**Example Dockerfile – Ubuntu**
For Debian derivatives, you also need to install certificate authority (CA) certificates to avoid issues when downloading the installer.
```
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
```
In your task definition, the configuration depends on the networking mode that you use. Bridge networking is the default and can be used in your default VPC. In a bridge network, set the `AWS_XRAY_DAEMON_ADDRESS` environment variable to tell the X-Ray SDK which container-port to reference and set the host port. For example, you could publish UDP port 2000, and create a link from your application container to the daemon container.
**Example Task definition**
```
{
"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"
]
}
```
If you run your cluster in the private subnet of a VPC, you can use the [`awsvpc` network mode](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html) to attach an elastic network interface (ENI) to your containers. This enables you to avoid using links. Omit the host port in the port mappings, the link, and the `AWS_XRAY_DAEMON_ADDRESS` environment variable.
**Example VPC task definition**
```
{
"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
}
]
}
]
}
```
## Configure command line options in the Amazon ECS console
Command line options override any conflicting values in your image's config file. Command line options are typically used for local testing, but can also be used for convenience while setting environment variables, or to control the startup process.
By adding command line options, you are updating the Docker `CMD` that is passed to the container. For more information, see [the Docker run reference](https://docs.docker.com/engine/reference/run/#overriding-dockerfile-image-defaults).
**To set a command line option**
1. Open the Amazon ECS classic console at [https://console.aws.amazon.com/ecs/](https://console.aws.amazon.com/ecs/).
1. From the navigation bar, choose the region that contains your task definition.
1. In the navigation pane, choose **Task Definitions**.
1. On the **Task Definitions** page, select the box to the left of the task definition to revise and choose **Create new revision**.
1. On the **Create new revision of Task Definition** page, select the container.
1. In the **ENVIRONMENT** section, add your comma-separated list of command line options to the **Command** field.
1. Choose **Update**.
1. Verify the information and choose **Create**.
The following example shows how to write a comma-separated command line option for the `RoleARN` option. The `RoleARN` option assumes the specified IAM role to upload segments to a different account.
**Example**
```
--role-arn, arn:aws:iam::123456789012:role/xray-cross-account
```
To learn more about the available command line options in X-Ray, see [Configuring the AWS X-Ray Daemon](xray-daemon-configuration.md).