Getting started
Lightbend Telemetry can capture data for applications using Akka libraries and modules. You can see a list of all the available metrics and instrumentations in Lightbend Telemetry documentation .
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 to use the Cinnamon Agent for one of the following build systems: sbt , Maven , or Gradle .
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
andmaven.compiler.target
to use Java 8. - Scala
-
build.sbt
ThisBuild / scalaVersion := "2.13.12" val AkkaVersion = "2.9.6"
Lightbend Telemetry supports other versions of Akka and Scala.
The Full Telemetry Documentation 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 that are necessary for your application. In this example, we add instrumentations for Akka , Akka Persistence , Akka Projection , 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 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.20.0")
And enable it in your project:
build.sbtenablePlugins(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.sbtaddSbtPlugin("com.github.sbt" % "sbt-native-packager" % "1.9.13")
And then configure it in your project:
project/plugins.sbtenablePlugins(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 that can be used to see the metrics locally in your terminal.
cinnamon {
chmetrics.reporters += "console-reporter"
}
A simple configuration for your Akka HTTP server will match all paths, hosts and ports:
cinnamon.akka.http.servers {
"*:*" {
paths {
"*" {
metrics = on
}
}
}
}
A similar configuration can be done for the client:
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. |