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 a Hello World example that illustrates Lightbend Telemetry basics. Within 30 minutes, you should be able to download and run the example and use this guide to understand how the example is constructed. This will get your feet wet, and hopefully inspire you to dive deeper into Lightbend Telemetry!

The example for Scala includes a distribution of sbt (build tool). You can run it on Linux, MacOS, or Windows.

  1. Download the zip file from Lightbend Tech Hub by clicking CREATE A PROJECT FOR ME.
  2. Extract the zip file to a convenient location:
  • On Linux and OSX systems, open a terminal and use the command unzip akka-quickstart-scala.zip. Note: On OSX, if you unzip using Archiver, you also have to make the sbt files executable: $ chmod u+x ./sbt $ chmod u+x ./sbt-dist/bin/sbt

  • On Windows, use a tool such as File Explorer to extract the project.

Running the example

To run Hello World:

  1. In a console, change directories to the top level of the unzipped project.

    For example, if you used the default project name, akka-quickstart-scala, and extracted the project to your root directory, from the root directory, enter: cd akka-quickstart-scala

  2. Enter ./sbt on OSX/Linux or sbt.bat on Windows to start sbt.

    sbt downloads project dependencies. The > prompt indicates sbt has started in interactive mode.

  3. At the sbt prompt, enter reStart.

    sbt builds the project and runs Hello World

The output should look something like this (scroll all the way to the right to see the Actor output):

[info] Compiling 1 Scala source and 1 Java source to /Users/x/akka-quickstart-scala/target/scala-2.12/classes...
[info] Running com.lightbend.akka.sample.AkkaQuickstart
[INFO] [05/09/2017 09:57:15.979] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/howdyGreeter#-1854995773]): Howdy, Akka
[INFO] [05/09/2017 09:57:15.980] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/helloGreeter#-1072877049]): Hello, Scala
[INFO] [05/09/2017 09:57:15.980] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/goodDayGreeter#1972065097]): Good day, Play
[INFO] [05/09/2017 09:57:15.980] [helloAkka-akka.actor.default-dispatcher-2] [akka://helloAkka/user/printerActor] Greeting received (from Actor[akka://helloAkka/user/howdyGreeter#-1854995773]): Howdy, Lightbend

Congratulations, you just ran your first Akka app. Now lets make some changes to add Lightbend Telemetry to our project.

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

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.12.9"

lazy val akkaVersion = "2.5.23"

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" % "3.0.8" % "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.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] [05/11/2017 14:07:20.790] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Hello, Java
[INFO] [05/11/2017 14:07:20.791] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Good day, Play
[INFO] [05/11/2017 14:07:20.791] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Howdy, Akka
[INFO] [05/11/2017 14:07:20.791] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Howdy, Lightbend
======================================================================
[info] -- Gauges ----------------------------------------------------------------------
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.active-threads
[info]              value = 0
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.parallelism
[info]              value = 12
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.pool-size
[info]              value = 4
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.queued-tasks
[info]              value = 0
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.running-threads
[info]              value = 0
[info] metrics.cinnamon.agent.2_11_2.java.1_8_0_131.scala.2_12_6.akka.2_5_21.versions
[info]              value = 1
[info] -- Counters --------------------------------------------------------------------
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.actors.com_example_Greeter.running-actors
[info]              count = 3
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.actors.com_example_Printer.running-actors
[info]              count = 1
[info] -- Histograms ------------------------------------------------------------------
[info] metrics.akka.systems.helloAkka.dispatchers.akka_actor_default-dispatcher.actors.com_example_Greeter.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.