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.
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.
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.
- On Linux and OSX systems, open a terminal and use the command
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.3</akka.version>
<!-- Declare Cinnamon version -->
<cinnamon.version>2.20.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.13</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.