Configure

Once the sandbox environment has been successfully installed, the next 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 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 sandbox.

Note: Cinnamon 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 sandbox dependency

Add the cinnamon-sandbox dependency to your application. This will transitively resolve all required dependencies and provides default configuration for the 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.11</artifactId>
  <version>2.6.2</version>
</dependency>
Gradle
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-sandbox_2.11', version: '2.6.2'

You then have two options for running your application, either within the ConductR sandbox as a ConductR bundle, or outside the ConductR sandbox. These approaches are described in the following sections.

Run application outside ConductR sandbox

You can run your application “outside” the ConductR sandbox, with data being sent to the Elasticsearch running in the sandbox. If your build tool is either Maven or Gradle then this is the suggested way to get started.

After adding the Cinnamon sandbox dependency, you can then run your application with the Cinnamon agent enabled, alongside the ConductR sandbox with monitoring feature enabled.

Run application as ConductR bundle

You can also run your application as a ConductR bundle within the ConductR sandbox. The metric and event reporters will then use ConductR’s service discovery to locate the Elasticsearch service.

Configuration

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