Need help with aws-xray-daemon?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

134 Stars 44 Forks Other 98 Commits 21 Opened issues


The AWS X-Ray daemon listens for traffic on UDP port 2000, gathers raw segment data, and relays it to the AWS X-Ray API.

Services available


Need anything else?

Contributors list

Build Status

AWS X-Ray Daemon

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.

Getting Help

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.

Sending Segment Documents

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{}

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  

Credential Configuration

The AWS X-Ray Daemon follows default credential resolution for the aws-sdk-go.

Follow the guidelines for the credential configuration.

Daemon Usage (command line args)

Usage: X-Ray [options]
1. -a --resource-arn Amazon Resource Name (ARN) of the AWS resource running the daemon.
2. -o --local-mode Don't check for EC2 instance metadata.
3. -m --buffer-memory Change the amount of memory in MB that buffers can use (minimum 3).
4. -n --region Send segments to X-Ray service in a specific region.
5. -b --bind Overrides default UDP address (
6. -t --bind-tcp Overrides default TCP address (
7. -r --role-arn Assume the specified IAM role to upload segments to a different account.
8. -c --config Load a configuration file from the specified path.
9. -f --log-file Output logs to the specified file path.
10. -l --log-level Log level, from most verbose to least: dev, debug, info, warn, error, prod (default).
11. -p --proxy-address Proxy address through which to upload segments. 12. -v --version Show AWS X-Ray daemon version. 13. -h --help Show this screen


make build
would build binaries and .zip files in
folder for Linux, MacOS, and Windows platforms.


make build-linux
would build binaries and .zip files in
folder for the Linux platform.


make build-mac
would build binaries and .zip files in
folder for the MacOS platform.


make build-windows
would build binaries and .zip files in
folder for the Windows platform.

Build for ARM achitecture

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
. 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

Pulling X-Ray Daemon image from ECR Public Gallery

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


aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin

Pull alpha tag from Public ECR Gallery

docker pull

Pull released version tag from Public ECR Gallery

docker pull

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. Public ECR Gallery will have release/stable version image tag starting from daemon 3.3.0 release.


make test
will run unit tests for the X-Ray daemon.


This library is licensed under the Apache 2.0 License.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.