Getting started

The main components of Lightbend Telemetry need to be installed, or integrated into your build, to enable telemetry for Akka.

This quick start guide takes you through the basic steps required to get your project up and running with Lightbend Telemetry.

1. Lightbend account and Bintray credentials

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

Once you have logged in you should set up the Bintray credentials for your specific build tool (sbt, Maven or Gradle).

Contact Lightbend to request an evaluation.

Tip: MS Windows users struggling to create a .lightbend folder in the home directory can do so by using the Terminal command: mkdir .lightbend.

2. Set up the Cinnamon Agent

Lightbend Telemetry is currently available for Akka, Play, and Lagom. To get started, you should configure your build to use the Cinnamon Agent for one of the following build systems: sbt, Maven, or Gradle.

3. Configure Cinnamon for telemetry

The heart of our system named “Cinnamon”, includes modules for selecting actors, HTTP services, streams, or persistent entities, reporting metrics and events, and tracing asynchronous flows.

Since your application could create thousands or even tens of thousands of actors, the default setting is configured with actor telemetry turned off. You need to select which actors to observe in your application.conf file which is the same file used to set up your Akka system.

Here below is a simple example configuration to instrument all actors in the system grouped by actor class:

cinnamon.akka {
  actors {
    "/user/*" {
      report-by = class
    }
  }
}

For more information see configuration for Akka, Akka HTTP, Play, Lagom, Akka Streams, or Akka Persistence.

4. Install and configure backend plugins

Lightbend Telemetry provides backend plugins for integrating with monitoring solutions and libraries for metrics and logging. Also, Telemetry supports multiple backend reporting, so you could configure one of the available backends to capture and process metrics while another handles events.

Let’s take a look at a sample application and what steps are needed to add Lightbend Telemetry for various build tools.