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, 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.

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.