Gradle Example: Akka

Here are instructions for how to take a sample application and add telemetry to it for Gradle. 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
  • Gradle
  • git
  • Bintray credentials

Bintray credentials

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

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!

To get started using Gradle, make sure you have an installation of Java 8 and an installation of Gradle. You can run the example project on Linux, MacOS, or Windows.

Download and unzip the example:

  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-java.zip.
  • On Windows, use a tool such as File Explorer to extract the project.

Running the example

Make sure that you have installed Gradle and thereafter open a Terminal window and, from inside the project directory, type the following to run Hello World:

Gradle:

$ gradle run

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

Gradle:

:compileJava UP-TO-DATE
:processResources NO-SOURCE
:classes UP-TO-DATE
:run
>>> Press ENTER to exit <<<
[INFO] [05/11/2017 14:08:22.884] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Howdy, Akka
[INFO] [05/11/2017 14:08:22.884] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Good day, Play
[INFO] [05/11/2017 14:08:22.884] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Hello, Java
[INFO] [05/11/2017 14:08:22.884] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Howdy, Lightbend
<=========----> 75% EXECUTING

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.

build.gradle

Add a build.gradle file with the following content:

apply plugin: 'scala'

repositories {
    mavenLocal()
}

repositories {
    maven {
      credentials {
        username 'your username'
        password 'your password'
      }
      mavenCentral()
      url = 'https://repo.lightbend.com/commercial-releases'
    }
}

// Add the agent to a separate configuration so it doesn't add to the normal class path
configurations {
  agent
}

def cinnamonVersion = '2.12.2'

dependencies {
  agent group: 'com.lightbend.cinnamon', name: 'cinnamon-agent', version: cinnamonVersion
  // Use Coda Hale Metrics and Akka instrumentation
  compile group: 'com.lightbend.cinnamon', name: 'cinnamon-chmetrics', version: cinnamonVersion
  compile group: 'com.lightbend.cinnamon', name: 'cinnamon-akka_2.12', version: cinnamonVersion
  compile group: 'com.typesafe.akka', name: 'akka-actor_2.12', version: '2.5.23'
}

apply plugin:'application'
mainClassName = "HelloAkkaScala"

run.doFirst {
  jvmArgs "-javaagent:${configurations.agent.singleFile}"
}

test.doFirst {
  jvmArgs "-javaagent:${configurations.agent.singleFile}"
}

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 Gradle to run the application:

> gradle run

The output should look something like this:

...
[[INFO] [05/11/2017 14:08:22.884] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Howdy, Akka
[info] Greeting: hello, lightbend	[INFO] [05/11/2017 14:08:22.884] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Good day, Play
[info] hello, lightbend	[INFO] [05/11/2017 14:08:22.884] [helloakka-akka.actor.default-dispatcher-2] [akka://helloakka/user/printerActor] Hello, Java
[info] hello, lightbend	[INFO] [05/11/2017 14:08:22.884] [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.