Getting started

Akka Insights 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 Akka Insights documentation new tab.

Akka provides Akka Insights (a.k.a. Cinnamon) for monitoring your deployments. Akka Insights 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 Akka Insights and explains how to get started, configure and run Akka Insights in production.

1. Subscriptions and credentials

Use of Akka Insights requires a subscription and credentials. An Akka 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. An Akka Subscription entitles you to use all commercial features and includes expert support.

Once you have a subscription, visit account.akka.io 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.15"
val AkkaVersion = "2.10.9"
Akka Insights supports other versions of Akka and Scala.

The Full Akka Insights 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 Akka Insights 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. Akka Insights Configuration

Akka Insights 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 Akka Insights, consider the free online course Monitoring Akka with Akka Insights in Akkademy.