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. For more information,
see AWS X-Ray Daemon.
The AWS X-Ray Daemon will enter maintenance mode on February 25, 2026. During maintenance mode, the X-Ray SDKs and Daemon will only receive critical bug fixes and security updates, and will not be updated to support new features.
We recommend that you migrate to AWS Distro for OpenTelemetry (ADOT) or OpenTelemetry Instrumentation to generate traces (through manual or zero-code instrumentation) from your application and send them to AWS X-Ray. OpenTelemetry is the industry-wide standard for tracing instrumentation and observability. It has a large open-source community for support and provides more instrumentations and updates. By adopting an OpenTelemetry solution, developers can leverage the latest services and innovations from AWS CloudWatch.
To gather traces from OpenTelemetry instrumentation and relay them to AWS X-Ray, you can use OpenTelemetry-compatible solutions such as the CloudWatch Agent, or the OpenTelemetry Collector. Read more about migrating to OpenTelemetry-compatible solutions to replace the X-Ray Daemon in the migration guide.
Use the following community resources for getting help with the AWS X-Ray Daemon. We use the GitHub issues for tracking bugs and feature requests.
- Ask a question in the AWS X-Ray Forum.
- Open a support ticket with AWS Support.
- If you think you may have found a bug, open an issue.
- For contributing guidelines refer CONTRIBUTING.md.
The X-Ray SDK sends segment documents to the daemon to avoid making calls to AWS directly. You can send the segment/subsegment in JSON over UDP port 2000
to the X-Ray daemon, prepended by the daemon header : {"format": "json", "version": 1}\n
{"format": "json", "version": 1}\n{<serialized segment data>}
For more details refer : Link
The AWS X-Ray Daemon is compatible with Go 1.8 and later.
Install the daemon using the following command:
go get -u github.com/aws/aws-xray-daemon/...
The AWS X-Ray Daemon follows default credential resolution for the aws-sdk-go.
Follow the guidelines for the credential configuration.
Usage: xray [options]
| Description | ||
|---|---|---|
| -a | --resource-arn | Amazon Resource Name (ARN) of the AWS resource running the daemon. |
| -o | --local-mode | Don't check for EC2 instance metadata. |
| -m | --buffer-memory | Change the amount of memory in MB that buffers can use (minimum 3). |
| -n | --region | Send segments to X-Ray service in a specific region. |
| -b | --bind | Overrides default UDP address (127.0.0.1:2000). |
| -t | --bind-tcp | Overrides default TCP address (127.0.0.1:2000). |
| -r | --role-arn | Assume the specified IAM role to upload segments to a different account. |
| -c | --config | Load a configuration file from the specified path. |
| -f | --log-file | Output logs to the specified file path. |
| -l | --log-level | Log level, from most verbose to least: dev, debug, info, warn, error, prod (default). |
| -p | --proxy-address | Proxy address through which to upload segments. |
| -v | --version | Show AWS X-Ray daemon version. |
| -h | --help | Show this screen |
Alongside the UDP listener that receives segment documents, the daemon runs an HTTP
signing proxy on its TCP address (-t, --bind-tcp, Socket.TCPAddress). The proxy
exists so that a co-located SDK can reach the X-Ray sampling API
without holding AWS credentials of its own: the daemon signs the request with its own
credentials and forwards it to X-Ray.
The proxy has no way to authenticate its callers, so it forwards only the two sampling
operations, GetSamplingRules and GetSamplingTargets. Any other request is answered
with 403 Forbidden and is neither signed nor forwarded, so the daemon's IAM role
cannot be used to write trace segments, read traces, or call the X-Ray control plane
through the proxy.
Because a caller still cannot be distinguished from any other, restrict who may reach
the TCP address. The default of 127.0.0.1:2000 limits it to the local host. Container
deployments that place the daemon in its own network namespace, such as an ECS bridge
sidecar or a Kubernetes DaemonSet, need a wider bind, and the daemon logs a warning when
it starts on one. In that case narrow access with a control outside the daemon, such as a
security group or a Kubernetes NetworkPolicy, and grant the daemon's role no more than
the AWSXRayDaemonWriteAccess
permissions it needs.
make build would build binaries and .zip files in /build folder for Linux, MacOS, and Windows platforms.
make build-linux would build binaries and .zip files in /build folder for the Linux platform.
make build-mac would build binaries and .zip files in /build folder for the MacOS platform.
make build-windows would build binaries and .zip files in /build folder for the Windows platform.
Currently, the make build script builds artifacts for AMD architecture. You can build the X-Ray Daemon for ARM by using the go build command and setting the GOARCH to arm64. To build the daemon binary on a linux ARM machine, you can use the following command:
GOOS=linux GOARCH=arm64 go build -ldflags "-s -w" -o xray cmd/tracing/daemon.go cmd/tracing/tracing.go
As of Aug 31, 2020, windows and darwin builds for ARM64 are not supported by go build.
Before pulling an image you should authenticate your docker client to the Amazon ECR public registry. For registry authentication options follow this link
Run below command to authenticate to public ECR registry using get-login-password (AWS CLI)
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
docker pull public.ecr.aws/xray/aws-xray-daemon:alpha
docker pull public.ecr.aws/xray/aws-xray-daemon:3.2.0
NOTE: We are not recommending to use daemon image with alpha tag in production environment. For production environment customer should pull in an image with released tag.
EC2 Instance Type: T2.Micro [1 vCPU, 1 GB Memory]
Collection time: 10 minutes per TPS (TPS = Number of segments sent to daemon in 1 second)
Daemon version tested: 3.3.6
| TPS | Avg CPU Usage (%) | Avg Memory Usage (MB) |
|---|---|---|
| 0 | 0 | 17.07 |
| 100 | 0.9 | 28.5 |
| 200 | 1.87 | 29.3 |
| 400 | 3.76 | 29.1 |
| 1000 | 9.36 | 29.5 |
| 2000 | 18.9 | 29.7 |
| 4000 | 38.3 | 29.5 |
make test will run unit tests for the X-Ray daemon.
This library is licensed under the Apache 2.0 License.