Getting started

Lightbend Telemetry new tab can capture data for applications using Akka libraries and modulesnew tab. You can see a list of all the available metrics and instrumentations in Lightbend Telemetry documentation new tab.

Lightbend provides Telemetry (a.k.a. Cinnamon) for Monitoring your deployments. Telemetry makes it possible to gather metric, event and trace information from your applications. The information is transferred to various backends. The rest of this documentation provides an overview of Telemetry and explains how to get started, configure and run Telemetry in production.

1. Subscriptions and credentials

Use of Lightbend Telemetry requires a subscription and credentials. A Lightbend subscription includes open source components that are distributed from the Maven Central Repository, as well as the commercial components which are distributed from a private repository. A Lightbend Subscription entitles you to use all commercial features and includes expert support.

Once you have a subscription, visit lightbend.com and login to learn how to add credentials to your development projects.

2. Set up Cinnamon Agent

To get started, you should configure your build new tab to use the Cinnamon Agent for one of the following build systems: sbt new tab, Maven new tab, or Gradle new tab.

2.1. Commercial Repositories

Here we assume that you have the repositories configured as environment variables that can be read by your build tool:

export LIGHTBEND_COMMERCIAL_MVN=https://repo.lightbend.com/...
export LIGHTBEND_COMMERCIAL_IVY=https://repo.lightbend.com/...

These values will be later read by your build tool.

Java
pom.xml
<repositories>
    <repository>
        <id>lightbend-commercial</id>
        <name>Lightbend Commercial</name>
        <url>${env.LIGHTBEND_COMMERCIAL_MVN}</url>
    </repository>
</repositories>
Scala
credentials.sbt
resolvers in ThisBuild ++= {
  val mvnResolver = sys.env.get("LIGHTBEND_COMMERCIAL_MVN").map { url =>
    "lightbend-commercial-mvn".at(url)
  }

  val ivyResolver = sys.env.get("LIGHTBEND_COMMERCIAL_IVY").map { u =>
    Resolver.url("lightbend-commercial-ivy", url(u))(Resolver.ivyStylePatterns)
  }

  (mvnResolver ++ ivyResolver).toList
}

2.2. Build Properties

Let’s define some version properties that will be reused later in multiple places of the build.

Java
pom.xml
<properties>
    <scala.version>2.13.3</scala.version>
    <scala.binary.version>2.13</scala.binary.version>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <version.number>${git.commit.time}-${git.commit.id.abbrev}</version.number>
</properties>
You don’t need all these properties and can skip or change some of them to match your project’s needs. For example, you can change maven.compiler.source and maven.compiler.target to use Java 8.
Scala
build.sbt
ThisBuild / scalaVersion := "2.13.12"
val AkkaVersion = "2.10.0"
Lightbend Telemetry supports other versions of Akka and Scala.

The Full Telemetry Documentation new tab contains more details and a complete sample.

2.3. Instrumenting your application

After adding the Cinnamon Agent as described above, make sure that you add the Cinnamon instrumentations new tab that are necessary for your application. In this example, we add instrumentations for Akka new tab, Akka Persistence new tab, Akka Projection new tab, Akka HTTP:

Java
pom.xml
<!-- Use Coda Hale Metrics -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-chmetrics</artifactId>
</dependency>
<!-- Use Akka instrumentations -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-akka_${scala.binary.version}</artifactId>
</dependency>
<!-- Use Akka Persistence instrumentation -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-akka-persistence_${scala.binary.version}</artifactId>
</dependency>
<!-- Akka Projection instrumentations -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-akka-projection_${scala.binary.version}</artifactId>
</dependency>
<!-- Use Akka HTTP instrumentation -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-akka-http_${scala.binary.version}</artifactId>
</dependency>
<!-- Use Akka gRPC instrumentation -->
<dependency>
    <groupId>com.lightbend.cinnamon</groupId>
    <artifactId>cinnamon-akka-grpc_${scala.binary.version}</artifactId>
</dependency>
Scala
build.sbt
libraryDependencies ++= Seq(
  // Use Coda Hale Metrics
  Cinnamon.library.cinnamonCHMetrics,
  // Use Akka instrumentation
  Cinnamon.library.cinnamonAkka,
  // Use Akka Persistence instrumentation
  Cinnamon.library.cinnamonAkkaPersistence,
  // Use Akka Projection instrumentation
  Cinnamon.library.cinnamonAkkaProjection,
  // Use Akka HTTP instrumentation
  Cinnamon.library.cinnamonAkkaHttp,
  // Use Akka gRPC instrumentation
  Cinnamon.library.cinnamonAkkaGrpc)

The Telemetry Documentation new tab contains full list of available instrumentations.

2.4. Run the application using Cinnamon Agent

Configure your build tool to use the agent.

Java
pom.xml
<!-- Copy the agent to a know location that can be referenced later -->
<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>
                        <overWrite>true</overWrite>
                        <destFileName>cinnamon-agent.jar</destFileName>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>
Scala

In Scala projects, you need to add Cinnamon sbt plugin instead.

project/plugins.sbt
// The Cinnamon Telemetry plugin
addSbtPlugin("com.lightbend.cinnamon" % "sbt-cinnamon" % "2.21.2")

And enable it in your project:

build.sbt
enablePlugins(Cinnamon)

Next, the agent needs to be added as a java command-line option. The following is an example of how to use the agent when running the application locally:

Java
pom.xml
<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>exec-maven-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
        <executable>java</executable>
        <arguments>
            <argument>-javaagent:${project.build.directory}/dependency/cinnamon-agent.jar</argument>
            <argument>-classpath</argument>
            <classpath />
            <argument>com.lightbend.telemetry.sample.Main</argument>
        </arguments>
    </configuration>
</plugin>
Scala
build.sbt
run / cinnamon := true

You can optionally use the agent when running tests.

Java
pom.xml
<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>
Scala
build.sbt
test / cinnamon := true

And also to include the agent JAR file when generating Docker images.

Java
pom.xml
<plugin>
    <groupId>io.fabric8</groupId>
    <artifactId>docker-maven-plugin</artifactId>
    <version>0.35.0</version>
    <configuration>
        <verbose>true</verbose>
        <useColor>true</useColor>
        <images>
            <image>
                <name>%a</name>
                <build>
                    <from>docker.io/library/eclipse-temurin:21.0.1_12-jre-jammy</from>
                    <tags>
                        <tag>${version.number}</tag>
                    </tags>
                    <entryPoint>
                        <exec>
                            <arg>java</arg>
                            <arg>-cp</arg>
                            <arg>/maven/*</arg>
                            <!-- /cinnamon-agent folder matches the assembly name below -->
                            <arg>-javaagent:/cinnamon-agent/cinnamon-agent.jar</arg>
                            <arg>com.lightbend.telemetry.sample.Main</arg>
                        </exec>
                    </entryPoint>
                    <assemblies>
                        <!-- An inline assembly to add the agent jar to the Docker image -->
                        <assembly>
                            <name>cinnamon-agent</name>
                            <mode>dir</mode>
                            <inline>
                                <includeBaseDirectory>false</includeBaseDirectory>
                                <fileSets>
                                    <fileSet>
                                        <directory>${project.build.directory}/dependency</directory>
                                        <outputDirectory>.</outputDirectory>
                                        <fileMode>0644</fileMode>
                                    </fileSet>
                                </fileSets>
                            </inline>
                        </assembly>
                        <assembly>
                            <descriptorRef>artifact-with-dependencies</descriptorRef>
                        </assembly>
                    </assemblies>
                </build>
            </image>
        </images>
    </configuration>
    <executions>
        <execution>
            <id>build-docker-image</id>
            <phase>package</phase>
            <goals>
                <goal>build</goal>
            </goals>
        </execution>
    </executions>
</plugin>
Scala

First, add sbt-native-packager to your project:

project/plugins.sbt
addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.9.13")

And then configure it in your project:

project/plugins.sbt
enablePlugins(JavaAppPackaging, DockerPlugin)
dockerBaseImage := "docker.io/library/eclipse-temurin:21.0.1_12-jre-jammy"
dockerUsername := sys.props.get("docker.username")
dockerRepository := sys.props.get("docker.registry")

3. Telemetry Configuration

Lightbend Telemetry supports a reporter new tab that can be used to see the metrics locally in your terminal.

src/main/resources/telemetry.conf
cinnamon {
  chmetrics.reporters += "console-reporter"
}

A simple configuration new tab for your Akka HTTP server will match all paths, hosts and ports:

src/main/resources/telemetry.conf
cinnamon.akka.http.servers {
  "*:*" {
    paths {
      "*" {
        metrics = on
      }
    }
  }
}

A similar configuration can be done for the client:

src/main/resources/telemetry.conf
cinnamon.akka.http.clients {
  "*:*" {
    paths {
      "*" {
        metrics = on
      }
    }
  }
}
🎓 To deepen your understanding of Lightbend Telemetry, consider the free online course Monitoring Akka with Lightbend Telemetry in Akkademy.