Menu
AWS X-Ray
Developer Guide

Running the X-Ray Daemon on AWS Elastic Beanstalk

You can run the X-Ray daemon on your Elastic Beanstalk environment's EC2 instances to relay trace data from your application to AWS X-Ray.

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.

AWS 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 checking an option in the Elastic Beanstalk console.

The daemon is installed on the instance and runs as a service when you enable the configuration option.

The version included on Elastic Beanstalk platforms may not be the latest version. See the Elastic Beanstalk release notes to find out the version of the daemon that is available for the platform configuration that you use.

Using Elastic Beanstalk's 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.

  2. Navigate to the management console for your environment.

  3. Choose Configuration.

  4. Choose Software Settings.

  5. For X-Ray daemon, choose Enabled.

  6. 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 fileC:\Progam Files\Amazon\XRay\cfg.yaml

  • Logsc:\Progam Files\Amazon\XRay\logs\xray-service.log

On Linux Platforms

  • Configuration file/etc/amazon/xray/cfg.yaml

  • Logs/var/log/xray/xray.log

You can tell Elastic Beanstalk to pull the daemon logs on demand by adding a file to the log tasks directory 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 Advanced Environment Customization with Configuration Files (.ebextensions) 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.amazonaws.com/aws-xray-assets.us-east-1/xray-daemon/aws-xray-daemon-1.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"

Example .ebextensions/xray.config - Windows Server

container_commands:
  01-execute-config-scirpt:
    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-1.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-east-1.amazonaws.com/aws-xray-assets.us-east-1/xray-daemon/aws-xray-daemon-windows-service-1.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 adds the daemon's log file to Elastic Beanstalk's tail logs task, to include it when you request logs with the console or Elastic Beanstalk Command Line Interface (EB CLI).