Maven

Lightbend Telemetry uses a Java Agent to add specially crafted instrumentation to the Lightbend Platform for efficient telemetry.

You will need to add this agent to your Maven build and deployment to enable the telemetry.

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.

If you do not have a Lightbend subscription, please contact us to request an evaluation.

Getting the Agent

To automatically pull down the agent as part of your build, you add the following plugin to download as part of the package task.

copy<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>2.19.3</version>
            <overWrite>true</overWrite>
            <destFileName>cinnamon-agent.jar</destFileName>
          </artifactItem>
        </artifactItems>
      </configuration>
    </execution>
  </executions>
</plugin>

Adding the Agent

Next, the agent needs to be added as a java command line option.

Here is a sample of how to add the agent to the exec plugin for the exec:exec task:

copy<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>3.0.0</version>
  <configuration>
    <executable>${JAVA_HOME}/bin/java</executable>
    <arguments>
      <argument>-classpath</argument>
      <classpath/>
      <argument>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argument>
      <argument>... your other arguments here ...</argument>
    </arguments>
  </configuration>
</plugin>

If you want to add the agent when running tests, you need to change the command line options for Maven Surefire Plugin:

copy<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-surefire-plugin</artifactId>
  <version>2.22.2</version>
  <configuration>
    <argLine>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argLine>
  </configuration>
</plugin>

When using docker-maven-plugin, for example if using reactive-app-maven-plugin, you can configure it to package cinnamon-agent.jar and add a correct java runtime flag.

We can define inline assembly rule for docker-maven-plugin to put cinnamon-agent inside our docker image like this:

<images>
  <image>
    ...
    <build>
      <assembly>
         <descriptorRef>artifact-with-dependencies</descriptorRef>
         <inline>
           <dependencySets>
             <dependencySet>
              <includes>
                <include>com.lightbend.cinnamon:cinnamon-agent</include>
              </includes>
              <outputDirectory>./jars</outputDirectory>
            </dependencySet>
          </dependencySets>
        </inline>
      </assembly>
    </build>
  </image>
</images>

And then add appropriate flags to use the agent:

<images>
  <image>
    ...
    <entryPoint>
      <exec>
        <arg>java</arg>
        <arg>-javaagent:./jars/cinnamon-agent.jar</arg>
        <arg>/opt/demo/server.jar</arg>
        ...
      </exec>
    </entryPoint>
  </image>
</images>

See the docker:build section docker-maven-plugin for more info.

Complete Sample

Here is a complete sample of a Maven build file configured to use the Cinnamon Agent, the Coda Hale Metrics plugin, Akka Instrumentation, and Akka HTTP Instrumentation.

copy<project>
  <modelVersion>4.0.0</modelVersion>

  <groupId>test.app</groupId>
  <artifactId>app</artifactId>
  <version>1.0-SNAPSHOT</version>

  <!--
    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>
    <!-- Use Coda Hale Metrics -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-chmetrics</artifactId>
      <version>2.19.3</version>
    </dependency>
    <!-- Use Akka instrumentation -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka_2.13</artifactId>
      <version>2.19.3</version>
    </dependency>
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-typed_2.13</artifactId>
      <version>2.19.3</version>
    </dependency>
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-persistence_2.13</artifactId>
      <version>2.19.3</version>
    </dependency>
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-stream_2.13</artifactId>
      <version>2.19.3</version>
    </dependency>
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-projection_2.13</artifactId>
      <version>2.19.3</version>
    </dependency>
    <!-- Use Akka HTTP instrumentation -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-http_2.13</artifactId>
      <version>2.19.3</version>
    </dependency>
    <!-- Use Akka gRPC instrumentation -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-grpc_2.13</artifactId>
      <version>2.19.3</version>
    </dependency>
    <dependency>
      <groupId>com.typesafe.akka</groupId>
      <artifactId>akka-actor_2.13</artifactId>
      <version>2.9.1</version>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <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>
      <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>2.19.3</version>
                  <overWrite>true</overWrite>
                  <destFileName>cinnamon-agent.jar</destFileName>
                </artifactItem>
              </artifactItems>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <executable>${JAVA_HOME}/bin/java</executable>
          <arguments>
            <argument>-classpath</argument>
            <classpath/>
            <argument>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argument>
            <argument>... your other arguments here ...</argument>
          </arguments>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>2.22.2</version>
        <configuration>
          <argLine>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argLine>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>