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 0.13.7 or higher. Set the sbt version in project/build.properties:

sbt.version=0.13.16

Bintray credentials

Follow these instructions to set up your Bintray credentials for sbt.

Lightbend Telemetry sbt plugin

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

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

credentials += Credentials(Path.userHome / ".lightbend" / "commercial.credentials")

resolvers += Resolver.url("lightbend-commercial",
  url("https://repo.lightbend.com/commercial-releases"))(Resolver.ivyStylePatterns)

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
cinnamon in run := true
cinnamon in test := 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"

The Cinnamon sbt plugin also adds the resolver necessary to download the cinnamon dependencies. If you don’t want to have the resolver added automatically, you should enable the CinnamonAgentOnly plugin instead.

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.5.0")

credentials += Credentials(Path.userHome / ".lightbend" / "commercial.credentials")

resolvers += Resolver.url("lightbend-commercial",
  url("https://repo.lightbend.com/commercial-releases"))(Resolver.ivyStylePatterns)

build.sbt

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

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

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

version := "1.0-SNAPSHOT"

scalaVersion := "2.11.11"

// Use Coda Hale Metrics
libraryDependencies += Cinnamon.library.cinnamonCHMetrics
// Use Akka instrumentation
libraryDependencies += Cinnamon.library.cinnamonAkka
libraryDependencies += Cinnamon.library.cinnamonAkkaHttp

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

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 cinnamonTakipi, and the instrumentation cinnamonAkka are required when instrumenting Akka.