Maven Example: Akka

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

Official sample

See a comprehensive sample application using Akka, Maven, and Lightbend Telemetry here: https://github.com/lightbend/telemetry-samples/tree/master/akka/shopping-cart-java.

Prerequisites

The following must be installed for these instructions to work:

Java (we recommend AdoptOpenJDK 11 or 17)
Maven
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 Maven, make sure you have an installation of Java 11 or 17 and an installation of Maven. 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 Maven and thereafter open a Terminal window and, from inside the project directory, type the following to run Hello World:

mvn compile exec:exec

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

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------< hello-akka-java:app >-------------------------
[INFO] Building app 1.0
[INFO] --------------------------------[ jar ]---------------------------------

...

[2020-02-18 17:58:41,498] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-18 17:58:41,500] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-3] [akka://helloakka/user/Charles] - Greeting 1 for Charles
[2020-02-18 17:58:41,500] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-3] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-18 17:58:41,500] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-3] [akka://helloakka/user/Charles] - Greeting 2 for Charles
[2020-02-18 17:58:41,501] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-18 17:58:41,501] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/Charles] - Greeting 3 for Charles

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.

pom.xml

Add a pom.xml file with the following content:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                      http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>hello-akka-java</groupId>
  <artifactId>app</artifactId>
  <version>1.0</version>

  <properties>
    <akka.version>2.9.1</akka.version>
    <!-- Declare Cinnamon version -->
    <cinnamon.version>2.19.3</cinnamon.version>
    <!-- The Scala binary version -->
    <scala.bin.version>2.13</scala.bin.version>
  </properties>

  <!--
    Generate your Lightbend commercial <repository> config for maven at:
    https://www.lightbend.com/account/lightbend-platform/credentials
  -->

  <repositories>
    <repository>
      <id>akka-repository</id>
      <name>Akka library repository</name>
      <url>https://repo.akka.io/maven</url>
    </repository>
  </repositories>

  <dependencies>
    <!-- Add Lightbend Telemetry (Cinnamon) dependencies -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka_${scala.bin.version}</artifactId>
      <version>${cinnamon.version}</version>
    </dependency>
    <!-- Use Coda Hale Metrics and Akka instrumentation -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-chmetrics</artifactId>
      <version>${cinnamon.version}</version>
    </dependency>
    <dependency>
      <groupId>com.typesafe.akka</groupId>
      <artifactId>akka-actor-typed_${scala.bin.version}</artifactId>
      <version>${akka.version}</version>
    </dependency>
    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <version>1.2.3</version>
    </dependency>
    <dependency>
      <groupId>com.typesafe.akka</groupId>
      <artifactId>akka-actor-testkit-typed_${scala.bin.version}</artifactId>
      <version>${akka.version}</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>4.13.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.scala-tools</groupId>
        <artifactId>maven-scala-plugin</artifactId>
        <version>2.15.2</version>
        <executions>
          <execution>
            <goals>
              <goal>compile</goal>
              <goal>testCompile</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <scalaVersion>2.13.12</scalaVersion>
          <jvmArgs>
            <jvmArg>-Xms64m</jvmArg>
            <jvmArg>-Xmx1024m</jvmArg>
          </jvmArgs>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.8.1</version>
        <configuration>
          <source>11</source>
          <target>11</target>
        </configuration>
      </plugin>
      <!-- Add plugin to correctly copy Lightbend Telemetry (Cinnamon) agent -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-dependency-plugin</artifactId>
        <version>3.1.2</version>
        <executions>
          <execution>
            <id>copy</id>
            <phase>compile</phase>
            <goals>
              <goal>copy</goal>
            </goals>
            <configuration>
              <artifactItems>
                <artifactItem>
                  <groupId>com.lightbend.cinnamon</groupId>
                  <artifactId>cinnamon-agent</artifactId>
                  <version>${cinnamon.version}</version>
                  <overWrite>true</overWrite>
                  <destFileName>cinnamon-agent.jar</destFileName>
                </artifactItem>
              </artifactItems>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <!-- Use agent when running the application -->
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <executable>${JAVA_HOME}/bin/java</executable>
          <arguments>
            <!-- Use Cinnamon agent when running the application -->
            <argument>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argument>
            <argument>-classpath</argument>
            <classpath />
            <argument>com.example.AkkaQuickstart</argument>
          </arguments>
        </configuration>
      </plugin>
      <!-- OPTIONAL: Use agent when running the tests -->
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.22.2</version>
        <configuration>
          <!-- Use Cinnamon agent when running the application -->
          <argLine>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argLine>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

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

> mvn compile package exec:exec

The output should look something like this:

...
[2020-02-19 13:41:36,387] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-4] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 13:41:36,390] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/Charles] - Greeting 1 for Charles
[2020-02-19 13:41:36,390] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-4] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 13:41:36,392] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/Charles] - Greeting 2 for Charles
[2020-02-19 13:41:36,393] [INFO] [com.example.Greeter] [helloakka-akka.actor.default-dispatcher-4] [akka://helloakka/user/greeter] - Hello Charles!
[2020-02-19 13:41:36,393] [INFO] [com.example.GreeterBot] [helloakka-akka.actor.default-dispatcher-5] [akka://helloakka/user/Charles] - Greeting 3 for Charles
2/19/20, 1:41:40 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_9.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.