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

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 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.11.1</version>
</dependency>
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-akka-http_2.12</artifactId>
  <version>2.11.1</version>
</dependency>
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-jvm-metrics-producer</artifactId>
  <version>2.11.1</version>
</dependency>
Gradle
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-akka_2.12', version: '2.11.1'
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-akka-http_2.12', version: '2.11.1'
compile group: 'com.lightbend.cinnamon', name: 'cinnamon-jvm-metrics-producer', version: '2.11.1'

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.