Monitoring Akka HTTP Applications with Kamon #

This guide walks you through setting up Kamon with an Akka HTTP application and sending your first metrics and traces to Kamon APM. The same steps will work if you choose any other reporter.

Before we start, make sure you are using Akka HTTP 10.1 or 10.2. Earlier Akka HTTP versions are not supported.

Let’s get to it!

1. Add the Kamon Dependencies #

Add the kamon-bundle and kamon-apm-reporter dependencies to your build.sbt file (or equivalent for other build tools):

      "io.kamon" %% "kamon-bundle" % "2.5.9",
      "io.kamon" %% "kamon-apm-reporter" % "2.5.9",

        <!--
            Ensure that the Scala version suffix (2.13 in this case)
            matches your Akka HTTP Scala version suffix!
        -->

        <dependency>
            <groupId>io.kamon</groupId>
            <artifactId>kamon-bundle_2.13</artifactId>
            <version>2.5.9</version>
        </dependency>
        <dependency>
            <groupId>io.kamon</groupId>
            <artifactId>kamon-apm-reporter_2.13</artifactId>
            <version>2.5.9</version>
        </dependency>

    // Ensure that the Scala version suffix (2.13 in this case)
    // matches your Akka HTTP Scala version suffix!

    implementation "io.kamon:kamon-bundle_2.13:2.5.9"
    implementation "io.kamon:kamon-apm-reporter_2.13:2.5.9"

The Kamon Bundle dependency contains all the Kamon automatic instrumentation modules in a single jar, so that you don’t need any additional dependencies. The APM reporter dependency is in charge of sending all your metrics and traces to Kamon APM.

2. Initialize Kamon #

Call Kamon.init() as the first thing in your main method:

object QuickstartApp {

  def main(args: Array[String]): Unit = {

    // This line initializes all Kamon components
    Kamon.init()

    // ... Your application code goes after this.

public class QuickstartApp {

    public static void main(String[] args) throws Exception {
        // This line initializes all Kamon components
        Kamon.init();

        // ... Your application code goes after this.

The call to Kamon.init() installs the automatic instrumentation on the JVM and starts sending data to Kamon APM (and any other reporters you might have). It is very important that the call to Kamon.init() happens before creating your ActorSystem instance, otherwise the automatic instrumentation will not be able to hook into all the Akka-related classes.

3. Configure the APM Reporter #

Add your service name and API key to the application.conf file:

kamon {
  environment.service = "Akka HTTP App"
  apm.api-key = "Your API Key"
}

You can copy your API key directly from Kamon APM.

Verifying the Installation #

Next time your application starts, Kamon should be up and running as well! Open http://localhost:5266/ in your browser and you’ll find the Kamon Status Page. It should look like this:

The important bits to check in the Status Page are that the modules have a green check mark and instrumentation is shown as active on the top-left corner. If your installation didn’t go well, please stop by our Github Discussions and post a question. We will do our best to help!

That is it, your installation is done! You might want to check out the How To Guides for common post-installation steps to improve your instrumentation.