Check out the New Service Map! Check out the all-new Kamon APM Service Map!

Setting up Kamon with Lagom Framework #

This guide walks you through setting up Kamon with a Lagom Framework 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 Lagom Framework 1.5 or 1.6. This guide might work with Lagom Framework 1.4 but we have not tested it.

Beware that Kamon will not work with Lagom applications on Development mode. The instructions below will enable the Kamon instrumentation for Production Mode only.

With that out of the way, let’s get to it!

1. Add the Kamon Dependencies #

Add the kamon-bundle and kamon-apm-reporter dependencies to the implementation projects (usually ending with -impl) in your build.sbt file:

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

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. Add the SBT Javaagent Plugin Dependency #

Add the SBT Javaagaent Plugin to your project/build.sbt file:

addSbtPlugin("com.lightbend.sbt" % "sbt-javaagent" % "0.1.6")

3. Enable the JavaAgent Plugin #

Include the JavaAgent plugin in the call to .enablePlugins and add a new value to the javaAgents setting with the Kanela agent in your build.sbt file:

lazy val `hello-impl` = (project in file("hello-impl"))
  .enablePlugins(LagomScala, JavaAgent)
    javaAgents += "io.kamon" % "kanela-agent" % "1.0.7",

Enabling the SBT Java Agent Plugin ensures that the Kamon instrumentation will be initialized properly when running in Production Mode.

4. Configure the APM Reporter #

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

kamon {
  environment.service = "Lagom Application"
  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.