Configure

The first step is to configure your application to use telemetry. This step is required so that Lightbend Telemetry knows what to instrument.

As part of the developer sandbox experience we provide a simplified way to configure your application. This section will describe how to set things up using the simplified way. We refer to the other sections of the documentation should you want to control in what way your application is being instrumented, how to report the data gathered, etc.

This section will take you through the required steps to configure your application for the developer sandbox.

Note: Cinnamon developer sandbox only supports Akka 2.5 or newer.

Bintray credentials

During the registration process for a Lightbend account you should have received Bintray credentials. These credentials will give you access to downloading the required Cinnamon packages. Click on your build tool environment to see the instructions for how to configure the Bintray credentials: sbt, Maven or Gradle.

Configure the Cinnamon agent

Lightbend Telemetry uses a Java agent that instruments the code in Lightbend libraries, e.g. Akka, that enables instrumentation to extract metrics, events and other data from these libraries. Without enabling this agent nothing will be collected so it is very important that you make sure to set it up. We provide specific instructions for: sbt, Maven or Gradle.

Cinnamon developer sandbox dependency

Add the cinnamon-sandbox dependency to your application. This will transitively resolve all required dependencies and provides default configuration for the developer sandbox environment.

First, add this resolver:

sbt
resolvers += "lightbend-contrail" at "https://dl.bintray.com/typesafe/commercial-maven-releases"
Maven
<repository>
  <id>lightbend-contrail</id>
  <name>Lightbend Contrail</name>
  <url>https://dl.bintray.com/typesafe/commercial-maven-releases</url>
</repository>
Gradle
maven {
  url = 'https://dl.bintray.com/typesafe/commercial-maven-releases'
}

Then add this dependency:

sbt
Cinnamon.library.cinnamonSandbox
Maven
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-sandbox_2.12</artifactId>
  <version>2.10.5</version>
</dependency>
Gradle
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-sandbox_2.12', version: '2.10.5'

Configuration

The Cinnamon developer sandbox dependency provides a default application.conf to configure instrumentation and reporting. By default, all user defined Akka actors will be instrumented, by actor class. For Akka HTTP, all servers and clients, for all paths, will have metrics enabled by default. These are good defaults to start with, but it is possible to tweak this default behavior as needed.

Overriding what to instrument

It is possible to override the default telemetry behavior by adding an application.conf file to your project and defining which actors to instrument using the key cinnamon.akka.actors. You can use and follow the actor configuration instructions for how to set up specific telemetry. Here is an example that shows you how to set up specific telemetry in the developer sandbox environment:

cinnamon.akka.actors {
  "com.example.a.A" {
    report-by = class
  }
  "com.example.a.b.*" {
    report-by = instance
  }
  "/user/x/y/*" {
    report-by = class
  }
}

For overriding the default telemetry for Akka HTTP, see the Akka HTTP configuration.