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.

Commercial 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 commercial credentials, the guide will instruct you how to update to using the new scheme.

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

copylibraryDependencies ++= Seq(
  Cinnamon.library.cinnamonAkka,
  Cinnamon.library.cinnamonAkkaHttp,
  Cinnamon.library.cinnamonJvmMetricsProducer
)

Maven

copy<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-akka_2.13</artifactId>
  <version>2.19.3</version>
</dependency>
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-akka-http_2.13</artifactId>
  <version>2.19.3</version>
</dependency>
<dependency>
  <groupId>com.lightbend.cinnamon</groupId>
  <artifactId>cinnamon-jvm-metrics-producer</artifactId>
  <version>2.19.3</version>
</dependency>

Gradle

copyimplementation group: 'com.lightbend.cinnamon', name: 'cinnamon-akka_2.13', version: '2.19.3'
implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-akka-http_2.13', version: '2.19.3'
implementation group: 'com.lightbend.cinnamon', name: 'cinnamon-jvm-metrics-producer', version: '2.19.3'

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

copycinnamon {
  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.