sbt Example: Akka

Here are instructions for how to take a sample application and add telemetry to it for sbt. In this example you will add Cinnamon and a Coda Hale Console reporter will be used to print telemetry output to the terminal window.

Prerequisites

The following must be installed for these instructions to work:

  • Java
  • sbt
  • git
  • Bintray credentials

Bintray credentials

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

Sample application

We are going to use Hello Akka as the sample application.

Open up a terminal window and execute the following:

> git clone https://github.com/typesafehub/activator-hello-akka.git
> cd activator-hello-akka

Make sure that the application can be compiled before continuing:

> sbt compile

Modifications

The modifications below are required to enable telemetry.

project/plugins.sbt

Lightbend Telemetry has a convenient sbt plugin that makes it easy to add the Cinnamon Java Agent to your build. Add the following plugin and repository to your project/plugins.sbt file:

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

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

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

Make sure that the credentials setting points to where you chose to create the commercial credentials file.

build.sbt

Open the file build.sbt and make it look this way:

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

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

name := "hello-akka"

version := "1.0"

scalaVersion := "2.11.11"

lazy val akkaVersion = "2.4.20"

libraryDependencies ++= Seq(
  // Use Coda Hale Metrics and Akka instrumentation
  Cinnamon.library.cinnamonCHMetrics,
  Cinnamon.library.cinnamonAkka,
  "com.typesafe.akka" %% "akka-actor" % akkaVersion,
  "com.typesafe.akka" %% "akka-testkit" % akkaVersion,
  "org.scalatest" %% "scalatest" % "2.2.6" % "test",
  "junit" % "junit" % "4.12" % "test",
  "com.novocode" % "junit-interface" % "0.11" % "test",
  "ch.qos.logback" % "logback-classic" % "1.1.3"
)

testOptions += Tests.Argument(TestFrameworks.JUnit, "-v")

Please note that the Scala and Akka versions may vary. Lightbend Telemetry currently supports Akka 2.3.x/2.4.x/2.5.x.

application.conf

Add a application.conf file to the folder src/main/resources with the following content:

cinnamon.application = "hello-akka"

cinnamon.akka {
  actors {
    "/user/*" {
      report-by = class
    }
  }
}
cinnamon.chmetrics {
  reporters += "console-reporter"
}

Running

When you have modified the files above you simply use sbt to run the application:

> sbt run

The output should look something like this:

...
[info] Greeting: hello, akka
[info] Greeting: hello, lightbend
[info] hello, lightbend
[info] hello, lightbend
[info] hello, lightbend
[info] hello, lightbend
[info] hello, lightbend
[info] 5/13/16 11:30:25 AM ============================================================
[info]
[info] -- Counters --------------------------------------------------------------------
[info] metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.actors.GreetPrinter.running-actors
[info]              count = 1
[info] metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.actors.Greeter.running-actors
[info]              count = 1
[info]
[info] -- Histograms ------------------------------------------------------------------
[info] metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.actors.GreetPrinter.mailbox-size
...

That is how easy it is to get started! You can find more information about configuration, plugins, etc. in the rest of this documentation.