Getting started

Language

Lightbend Telemetry new tab can capture data for applications using Akka libraries and modules new 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/...

shell script

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>

xml

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
}

scala

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>

xml

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.1"

scala

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>

xml

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)

scala

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>

xml

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")

scala

And enable it in your project:

build.sbt

enablePlugins(Cinnamon)

scala

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>

xml

Scala

build.sbt

run / cinnamon := true

scala

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>

xml

Scala

build.sbt

test / cinnamon := true

scala

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>

xml

Scala

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

project/plugins.sbt

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

scala

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")

scala

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"
}

hocon

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
      }
    }
  }
}

hocon

A similar configuration can be done for the client:

src/main/resources/telemetry.conf

cinnamon.akka.http.clients {
  "*:*" {
    paths {
      "*" {
        metrics = on
      }
    }
  }
}

hocon

🎓 To deepen your understanding of Lightbend Telemetry, consider the free online course Monitoring Akka with Lightbend Telemetry in Akkademy.