Monitoring Play Framework Applications with Kamon #

This guide walks you through setting up Kamon with a Play 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 Play Framework 2.6, 2.7 or 2.8. This guide assumes that you have a Play Framework project using SBT as the build tool, and that you are not using a custom Application Loader (see the special cases section below).

Let’s get to it!

1. Add the Kamon Dependencies #

Add the kamon-bundle and kamon-apm-reporter dependencies to your build.sbt file:

libraryDependencies += "io.kamon" %% "kamon-bundle" % "2.5.9"
libraryDependencies += "io.kamon" %% "kamon-apm-reporter" % "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. Add the SBT Kanela Runner Plugin #

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

// For Play Framework 2.8.8
addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.8" % "2.0.14")

// OR for Play Framework <= 2.8.7
addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.8" % "2.0.10")

Make sure that the play-2.x suffix matches your Play Framework version.

The SBT Kanela Runner Plugin ensures that Kamon’s instrumentation is applied when you hit run from the SBT console on Play Framework projects (a.k.a. Development Mode). See the special cases below if you want to enable instrumentation in Production Mode only.

3. Enable the JavaAgent Plugin #

Include the JavaAgent plugin in the call to .enablePlugins in your build.sbt file:

lazy val root = (project in file(".")).enablePlugins(PlayScala, JavaAgent)

The SBT Java Agent Plugin is downloaded as a depency of the SBT Kanela Runner Plugin, you only need to enable it. 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 conf/application.conf file:

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

Special Cases #

Custom Application Loaders #

If your Play Framework application has a custom ApplicationLoader, you will need to add a few lines of code to ensure that Kamon is initialized and stopped properly. Add these lines to the load method in your ApplicationLoader implementation:

import kamon.Kamon

class MyApplicationLoader extends ApplicationLoader {
  def load(context: ApplicationLoader.Context): Application = {

    // For Kamon 2.3.1+
    Kamon.initWithoutAttaching(context.initialConfiguration.underlying)

    // For Kamon 2.3.0 and earlier versions
    //   - The reconfigure call ensures that Kamon is configured with 
    //     Play's configuration file from `conf/application.conf`
    //   - The second line starts reporters and system metrics collection
    Kamon.reconfigure(context.initialConfiguration.underlying)
    Kamon.loadModules()


    // Ensures that Kamon stops after every run. Specially important
    // when running on Development mode.
    context.lifecycle.addStopHook { () =>
      Kamon.stop()
    }

    new MyComponents(context).application
  }
}

Using Instrumentation in Production Mode Only #

If you want to use Kamon’s instrumentation in Production Mode only, you can skip the SBT Kanela Runner Plugin and use the sbt-javaagent plugin directly.

To swap the plugins, remove the SBT Kanela Runner Plugin from Step #2 and add this line instead:

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

Then, add the javaAgents option to your Play project, pointing to the Kanela agent:

javaAgents += "io.kamon" % "kanela-agent" % "1.0.16"

That’s it. The rest of the installation steps remain the same.