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 agent to your Maven build and deployment to enable the telemetry.

Bintray credentials

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

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.

<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.11.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:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <version>1.6.0</version>
  <configuration>
    <executable>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>

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.

<project>
  <modelVersion>4.0.0</modelVersion>

  <groupId>test.app</groupId>
  <artifactId>app</artifactId>
  <version>1.0-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 -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-chmetrics</artifactId>
      <version>2.11.3</version>
    </dependency>
    <!-- Use Akka instrumentation -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka_2.12</artifactId>
      <version>2.11.3</version>
    </dependency>
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-stream_2.12</artifactId>
      <version>2.11.3</version>
    </dependency>
    <!-- Use Akka HTTP instrumentation -->
    <dependency>
      <groupId>com.lightbend.cinnamon</groupId>
      <artifactId>cinnamon-akka-http_2.12</artifactId>
      <version>2.11.3</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.11.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>1.6.0</version>
        <configuration>
          <executable>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>
    </plugins>
  </build>
</project>