Configure

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

This section will describe how to set things up. 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.

Bintray credentials

To gain access to Lightbend Telemetry you must have a Lightbend subscription and Lightbend account.

Once you have logged in, the Lightbend platform credentials guide contains instructions for configuring your sbt, maven or gradle project to access Lightbend’s commercial dependencies, including Telemetry. If you have previously used a username and password to configure your Bintray credentials, the guide will instruct you how to update to using the new scheme.

Note: The URLs generated as part of your Lightbend platform credentials should not be committed to public source control repositories.

If you do not have a Lightbend subscription, please contact us to request an evaluation.

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 dependencies

Add the Cinnamon dependencies to your application. In this example we will add akka and akka-http Cinnamon modules:

sbt
libraryDependencies ++= Seq(
  Cinnamon.library.cinnamonAkka,
  Cinnamon.library.cinnamonAkkaHttp,
  Cinnamon.library.cinnamonJvmMetricsProducer
)
Maven
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-akka_2.12</artifactId>
  <version>2.14.2</version>
</dependency>
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-akka-http_2.12</artifactId>
  <version>2.14.2</version>
</dependency>
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-jvm-metrics-producer</artifactId>
  <version>2.14.2</version>
</dependency>
Gradle
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-akka_2.12', version: '2.14.2'
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-akka-http_2.12', version: '2.14.2'
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-jvm-metrics-producer', version: '2.14.2'

Configuration

Here is an example of application.conf to configure instrumentation. 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.

application.conf
cinnamon {
  akka.actors = {
    default-by-class {
      includes = "/user/*"
      report-by = class
    }
  }

  akka.dispatchers = {
    basic-information {
      names = ["*"]
    }
    time-information {
      names = ["*"]
    }
  }

  akka.remote = {
    serialization-timing = on
    failure-detector-metrics = on
  }

  akka.cluster = {
    domain-events = on
    member-events = on
    singleton-events = on
    shard-region-info = on
  }

  akka.http = {
    servers {
      "*:*" {
        paths {
          "*" {
            metrics = on
          }
        }
      }
    }
    clients {
      "*:*" {
        paths {
          "*" {
            metrics = on
          }
        }
      }
    }
  }
}

You can use and follow the actor configuration instructions for how to set up specific telemetry. For Akka HTTP, see the Akka HTTP configuration.

The next sections contain sandbox specific reporting configuration.