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.

Prerequisites

The following must be installed for these instructions to work:

  • Java
  • Maven
  • git
  • Bintray credentials

Bintray credentials

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

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 8 and an installation of Maven. 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 Maven and thereafter open a Terminal window and, from inside the project directory, type the following to run Hello World:

Maven:

$ mvn compile exec:exec

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

Maven:

[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Building app 1.0
[INFO] ------------------------------------------------------------------------
[INFO]
[INFO] --- exec-maven-plugin:1.6.0:exec (default-cli) @ app ---
>>> Press ENTER to exit <<<
[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

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.

pom.xml

Add a pom.xml file with the following content:

<project>
    <modelVersion>4.0.0</modelVersion>

    <groupId>hello-akka</groupId>
    <artifactId>app</artifactId>
    <version>0.1-SNAPSHOT</version>

    <repositories>
      <repository>
        <id>lightbend-commercial</id>
        <name>Lightbend Commercial</name>
        <url>https://lightbend.bintray.com/commercial-releases</url>
      </repository>
    </repositories>

    <dependencies>
        <!-- Use Coda Hale Metrics and Akka instrumentation -->
        <dependency>
            <groupId>com.lightbend.cinnamon</groupId>
            <artifactId>cinnamon-chmetrics</artifactId>
            <version>2.12.2</version>
        </dependency>
        <dependency>
            <groupId>com.lightbend.cinnamon</groupId>
            <artifactId>cinnamon-akka_2.12</artifactId>
            <version>2.12.2</version>
        </dependency>
        <dependency>
            <groupId>com.typesafe.akka</groupId>
            <artifactId>akka-actor_2.12</artifactId>
            <version>2.5.23</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.0</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-dependency-plugin</artifactId>
                <version>3.1.1</version>
                <executions>
                    <execution>
                        <id>copy</id>
                        <phase>package</phase>
                        <goals>
                            <goal>copy</goal>
                        </goals>
                        <configuration>
                            <artifactItems>
                              <artifactItem>
                                <groupId>com.lightbend.cinnamon</groupId>
                                <artifactId>cinnamon-agent</artifactId>
                                <version>2.12.2</version>
                                <overWrite>true</overWrite>
                                <destFileName>cinnamon-agent.jar</destFileName>
                              </artifactItem>
                            </artifactItems>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
              <groupId>org.scala-tools</groupId>
              <artifactId>maven-scala-plugin</artifactId>
              <executions>
                <execution>
                  <goals>
                    <goal>compile</goal>
                    <goal>testCompile</goal>
                  </goals>
                </execution>
              </executions>
              <configuration>
                <jvmArgs>
                  <jvmArg>-Xms64m</jvmArg>
                  <jvmArg>-Xmx1024m</jvmArg>
                </jvmArgs>
              </configuration>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>1.6.0</version>
                <configuration>
                    <executable>java</executable>
                    <arguments>
                        <argument>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argument>
                        <argument>-classpath</argument>
                        <classpath />
                        <argument>HelloAkkaScala</argument>
                    </arguments>
                </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/*" {
      report-by = class
    }
  }
}
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:

...
[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.