Menu
AWS X-Ray
Developer Guide

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

You can download the daemon from Amazon S3.

Run the daemon from a command line.

~/Downloads$ ./xray

For detailed platform-specific instructions, see the following:

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. Locally, save your access keys to a file named credentials in your user directory under a folder named .aws.

Example ~/.aws/credentials

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

For more information about providing credentials to an SDK, see 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, create an IAM user and save its access keys on your computer.

To create an instance profile for use with X-Ray on Amazon EC2

  1. Open the IAM console.

  2. Choose Roles.

  3. Choose Create New Role.

  4. For Role Name, type xray-instance-profile. Choose Next Step.

  5. For Role Type, choose Amazon EC2.

  6. Attach managed policies to give your application access to AWS services.

    • AWSXrayWriteOnlyAccess – Gives the X-Ray daemon permission to upload trace data.

    • AmazonS3ReadOnlyAccess – Gives the instance permission to download the X-Ray daemon from Amazon S3.

    If your application uses the AWS SDK to access other services, add policies that grant access to those services.

  7. Choose Next Step.

  8. Choose Create Role.

To add X-Ray write permissions to an IAM user, group, or role

  1. Open the IAM console.

  2. Open the role associated with your instance profile, your IAM user, or your IAM user's group.

  3. Under Permissions, add the following managed policies.

    • AWSXrayWriteOnlyAccess – Gives the X-Ray daemon permission to upload trace data.

    • AmazonS3ReadOnlyAccess – Gives the instance or IAM user permission to download the X-Ray daemon from Amazon S3.

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

Configuring the Daemon

You can use command line options to customize the daemon's behavior.

Command line options

  • -b, --bind – Bind the daemon to a different port.

    --bind "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, --memory-limit – Change the amount of memory (in MiB) that the daemon can use.

    --memory-limit 150

    Default – 5% 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"
  • -v, --version – Show AWS X-Ray daemon version.

  • -h, --help – Show the help screen.

You can load a YAML format configuration file with the --config option.

Configuration file options

  • LocalMode – Set to true to skip checking for EC2 instance metadata.

  • Logging – Configure logging behavior.

    • LogLevel – Change the log level, from most verbose to least: dev, debug, info, warn, error, prod (default).

    • LogPath – Output logs to the specified file path.

  • Processor – Configure the daemon process.

    • Region – Specify a region to send trace data to that region instead of the current region.

  • RoleARN – Assume the specified IAM role to upload segments to a different account.

  • Socket – Configure the daemon's binding.

    • UDPAddress – Change the port on which the daemon listens.

Example xray-daemon.yaml

Socket:
  UDPAddress: "127.0.0.1:3000"
Processor:
  Region: "us-east-2"
Logging:
  LogLevel: "warn"
  LogPath: "/var/log/xray-daemon.log"
LocalMode: true
RoleARN: "arn:aws:iam::123456789012:role/xray-cross-account"

Pass the configuration file to the daemon by using the -c option.

~$ ./xray -c ~/xray-daemon.yaml