AWS X-Ray Tracing support

Lightbend Telemetry 2.16.1+ can report traces to AWS X-Ray new tab using the AWS Distro new tab and the Zipkin reporter new tab.

Note that Lightbend Telemetry doesn’t send traces directly to AWS X-Ray. You will need to set up the AWS OTel Collector new tab within your EKS cluster. Lightbend Telemetry uses Zipkin protocol to send traces to the AWS OTel Collector which batches them and then pushes them to the AWS X-Ray backend.

First, you will need to install the AWS OTel Collector into your EKS cluster. We provide a Pulumi script that automates EKS cluster and Akka Operator setup. It also has an option to install the AWS OTel Collector. Please follow instructions on the AWS OTel Collector installation page.

If you don’t use Pulumi then follow the Getting Started with the AWS Distro for OpenTelemetry Collector instruction.

Once you have the AWS OTel Collector deployed you will need to configure your application.

To enable your application for trace production, you will need to set up the Cinnamon agent as described on the Lightbend Telemetry Getting started new tab page.

After that, you will need to add tracing-specific configuration and dependencies.

The following are the core Cinnamon and Zipkin reporter dependencies that you will need to add to your build tool configuration:

Java
pom.xml
<!-- Cinnamon OpenTracing core dependency -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-opentracing_${scala.binary.version}</artifactId>
    <version>${lightbend.cinnamon.version}</version>
</dependency>
<!-- Cinnamon OpenTracing Zipkin reporter dependency -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-opentracing-zipkin</artifactId>
    <version>${lightbend.cinnamon.version}</version>
</dependency>
Scala
build.sbt
libraryDependencies ++= Seq(
  Cinnamon.library.cinnamonOpenTracing,
  Cinnamon.library.cinnamonOpenTracingZipkin)

After you have made that alteration, enable Lightbend Telemetry X-Ray support new tab (only available in Lightbend Telemetry 2.16.1+) and configure Zipkin reporter to send traces to the AWS OTel Collector:

src/main/resources/telemetry.conf
cinnamon.opentracing {
  // Lightbend Telemetry 2.16.1+ only
  tracer.aws-xray-trace-id-format = on
  zipkin {
    url-connection {
      endpoint = "http://<awsOTelCollectorServiceEndpoint>:9411/api/v2/spans"
    }
  }
}

Lightbend Telemetry provides a wide variety of tracing options you can find in the Lightbend Telemetry documentation new tab.

As an example you can use the next configuration to enable HTTP client and server tracing:

src/main/resources/telemetry.conf
cinnamon.akka.http {
  servers {
    "*:*" {
      paths {
        "*" {
          traceable = on
        }
      }
    }
  }
  clients {
    "*:*" {
      paths {
        "*" {
          traceable = on
        }
      }
    }
  }
}

Once the application is configured and deployed the traces will appear at the AWS X-Ray console.