sbt

Lightbend Telemetry uses a Java Agent to add specially crafted instrumentation to the Lightbend Platform for efficient telemetry.

You will need to add this agent to your sbt build and deployment to enable the telemetry.

Required sbt version

Make sure that your project is using an sbt version of 1.0.0 or higher. Set the sbt version in project/build.properties:

sbt.version=1.9.7

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.

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.

Lightbend Telemetry sbt plugin

We provide a convenient sbt plugin, called sbt-cinnamon, that makes it easy to add the Cinnamon Java Agent to your build. To use this plugin, add the following plugin to your project/plugins.sbt file:

addSbtPlugin("com.lightbend.cinnamon" % "sbt-cinnamon" % "2.20.4")

Note

The sbt-cinnamon plugin is published to the public sbt plugins repository, you must add the Lightbend commercial resolvers to your project (as described in the Commercial credentials section) to be able to download the rest of the Telemetry dependencies.

Next, you need to add the sbt-cinnamon plugin to your project by enabling it in your build.sbt:

// Enable the Lightbend Telemetry (Cinnamon) sbt plugin
lazy val app = project in file(".") enablePlugins (Cinnamon)

Enabling the plugin automatically adds the Cinnamon Agent to your dist scope, which in turn attaches the Agent to your distribution when using sbt-native-packager. If you want to utilize the agent while running or testing, then you will need to add the following to your build.sbt as well:

// Add the Cinnamon Agent for run and test
run / cinnamon := true
test / cinnamon := true

There is also a convenient way to set the log level of the Cinnamon Agent in your build.sbt file:

// Set the Cinnamon Agent log level
cinnamonLogLevel := "INFO"

Complete sample

Here is a complete sample of sbt plugins and build files configured to use the Cinnamon Agent and the Coda Hale Metrics integration, Akka Instrumentation, and Akka HTTP Instrumentation.

project/plugins.sbt

addSbtPlugin("com.lightbend.cinnamon" % "sbt-cinnamon" % "2.20.4")

build.sbt

// Enable the Lightbend Telemetry (Cinnamon) sbt plugin
lazy val app = project in file(".") enablePlugins (Cinnamon)

// Generate your Lightbend commercial sbt resolvers at:
//   https://www.lightbend.com/account/lightbend-platform/credentials

cinnamonSuppressRepoWarnings := true

// Add the Cinnamon Agent for run and test
run / cinnamon := true
test / cinnamon := true

// Set the Cinnamon Agent log level
cinnamonLogLevel := "INFO"

version := "1.0-SNAPSHOT"

scalaVersion := "2.13.13"

// Use Coda Hale Metrics
libraryDependencies += Cinnamon.library.cinnamonCHMetrics
// Use Akka instrumentation
libraryDependencies += Cinnamon.library.cinnamonAkka
libraryDependencies += Cinnamon.library.cinnamonAkkaTyped
libraryDependencies += Cinnamon.library.cinnamonAkkaPersistence
libraryDependencies += Cinnamon.library.cinnamonAkkaStream
libraryDependencies += Cinnamon.library.cinnamonAkkaProjection
// Use Akka HTTP instrumentation
libraryDependencies += Cinnamon.library.cinnamonAkkaHttp
// Use Akka gRPC instrumentation
libraryDependencies += Cinnamon.library.cinnamonAkkaGrpc
// Use Akka Cluster instrumentation
libraryDependencies += Cinnamon.library.cinnamonAkkaCluster

resolvers += "Akka library repository".at("https://repo.akka.io/maven")

libraryDependencies += "com.typesafe.akka" %% "akka-actor" % "2.9.7"

As you can see, the sbt-cinnamon plugin also has helpers for adding Cinnamon dependencies to your build. For example, different backend plugins such as cinnamonCHMetrics or specific instrumentations like cinnamonAkka.

Backend dependencies cinnamonCHMetrics or cinnamonPrometheus, and the instrumentation cinnamonAkka are required when instrumenting Akka.