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 (we recommend AdoptOpenJDK 11 or 17)
Gradle
Commercial credentials

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.

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 11 or 17 and an installation of Gradle. You can run the example project on Linux, MacOS, or Windows.

Download and unzip the example:

Download the zip file from Lightbend Tech Hub by clicking CREATE A PROJECT FOR ME.
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 run

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

> Task :run
SLF4J: A number (1) of logging calls during the initialization phase have been intercepted and are
SLF4J: now being replayed. These are subject to the filtering rules of the underlying logging system.
[2020-02-19 13:49:35,755] [INFO] [akka.event.slf4j.Slf4jLogger] [helloakka-akka.actor.default-dispatcher-3] [] - Slf4jLogger started
SLF4J: See also http://www.slf4j.org/codes.html#replay
>>> Press ENTER to exit <<<
[2020-02-19 13:49:35,790] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 13:49:35,792] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-3] [akka://helloakka/user/Charles] - Greeting 1 for Charles
[2020-02-19 13:49:35,793] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 13:49:35,793] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-3] [akka://helloakka/user/Charles] - Greeting 2 for Charles
[2020-02-19 13:49:35,793] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 13:49:35,794] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-3] [akka://helloakka/user/Charles] - Greeting 3 for Charles
<======<==========---> 80% EXECUTING [19s]

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 Lightbend Telemetry.

build.gradle

Add a build.gradle file with the following content:

plugins {
  id 'java'
  id 'application'
  id 'scala'
}

repositories {
    mavenCentral()
    mavenLocal()
    maven {
      url "https://repo.akka.io/maven"
    }
    // maven {
    //	   Generate your Lightbend commercial repositories config for gradle at:
    //	     https://www.lightbend.com/account/lightbend-platform/credentials
    // 	   url = '...'
    // }
}

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

// The Cinnamon version
def cinnamonVersion = '2.19.3'

def scalaBinVersion = '2.13'
def akkaVersion = '2.9.1'

dependencies {
  // Lightbend Telemetry (Cinnamon) agent
  agent "com.lightbend.cinnamon:cinnamon-agent:${cinnamonVersion}"
  // Use Coda Hale Metrics and Akka instrumentation
  implementation "com.lightbend.cinnamon:cinnamon-chmetrics:${cinnamonVersion}"
  implementation "com.lightbend.cinnamon:cinnamon-akka_${scalaBinVersion}:${cinnamonVersion}"

  implementation "com.typesafe.akka:akka-actor-typed_${scalaBinVersion}:${akkaVersion}"
  implementation "ch.qos.logback:logback-classic:1.2.3"
  testImplementation "com.typesafe.akka:akka-actor-testkit-typed_${scalaBinVersion}:${akkaVersion}"
  testImplementation "junit:junit:4.12"
}

mainClassName = "com.example.AkkaQuickstart"

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

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

run {
  standardInput = System.in
}

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/*" {
      # WARNING: In a real application, it will be better to tag the actors
      # so that will be easier to make sense of the metrics. But since this is
      # just a sample, we are using `instance` to keep it simple.
      # See the following page for more information:
      # https://developer.lightbend.com/docs/telemetry/current/instrumentations/akka/actors-typed.html
      report-by = instance
    }
  }
}

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:

...
[2020-02-19 14:13:03,199] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-4] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 14:13:03,203] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/Charles] - Greeting 1 for Charles
[2020-02-19 14:13:03,204] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-4] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 14:13:03,204] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/Charles] - Greeting 2 for Charles
[2020-02-19 14:13:03,204] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-4] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 14:13:03,205] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/Charles] - Greeting 3 for Charles
2/19/20, 2:13:07 PM ============================================================

-- Gauges ----------------------------------------------------------------------
metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.active-threads
             value = 0
metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.parallelism
             value = 12
metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.pool-size
             value = 2
metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.queued-tasks
             value = 0
metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.running-threads
             value = 0
metrics.akka.systems.helloakka.dispatchers.akka_actor_internal-dispatcher.active-threads
             value = 0
metrics.akka.systems.helloakka.dispatchers.akka_actor_internal-dispatcher.parallelism
             value = 12
metrics.akka.systems.helloakka.dispatchers.akka_actor_internal-dispatcher.pool-size
             value = 2
metrics.akka.systems.helloakka.dispatchers.akka_actor_internal-dispatcher.queued-tasks
             value = 0
metrics.akka.systems.helloakka.dispatchers.akka_actor_internal-dispatcher.running-threads
             value = 0
metrics.cinnamon.agent.2_13_2.java.11_0_6.scala.2_12_10.akka.2_6_3.versions
             value = 1

-- Counters --------------------------------------------------------------------
metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.actors.akka_actor_typed_internal_adapter_ActorAdapter.running-actors
             count = 1

-- Histograms ------------------------------------------------------------------
metrics.akka.systems.helloakka.dispatchers.akka_actor_default-dispatcher.actors.akka_actor_typed_internal_adapter_ActorAdapter.mailbox-size
             count = 2
               min = 1
               max = 1
...

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