Documentation

Instrumentation Agent Setup

In most situations, you wont need to do anything special to setup the agent other than following the directions on the Get Started guide, since either the Kamon.init() call or the SBT plugins will take care of attaching Kanela at runtime, but we are packing all the different options together in this guide for reference in case you need them.

In a Nutshell

All you need to do is download the latest release from our Kanela releases repository and start your JVM with the -javaagent:path-to-kanela.jar JVM option. For example, if you are running your application from IntelliJ IDEA you will need to add the -javaagent option to the “VM options” section as shown bellow:

And that is pretty much it. Even though it is a simple task, it can be challenging in different environments so please, follow the instructions bellow when:

  1. Running applications from SBT
  2. Running a Play Framework application on development mode
  3. Packaging applications with sbt-native-packager

Running from SBT

The simplest solution is to use the sbt-kanela-runner plugin. This plugin will ensure that the instrumentation is applied to your classes regardless of whether you are forking the process (via fork in run := true) or not. To get it working add these lines to your project/plugins.sbt file:

addSbtPlugin("io.kamon" % "sbt-kanela-runner" % "2.0.3")

That’s it! Next time your application starts, instrumentation will be enabled.

Play Framework

Once again, the sbt-kanela-runner plugin is the way to go. The plugin has special variants for Play applications that will have special treatment of Play’s infrastructure for running on Development mode, to include it you must add the right plugin depending on your Play version:

Play 2.7

addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.7" % "2.0.3")

Play 2.6

addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.6" % "2.0.3")

The runner brings the sbt-javaagent dependency with it, but it requires you to active it explicily by calling .enablePlugin(JavaAgent) on the right project instance in your build.sbt file, it should look like this:

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

Using sbt-native-packager

You can use the sbt-javaagent plugin together with sbt-native-packager to get the Kanela agent option automatically added to the startup scripts. To achieve this, first add the plugin to your project/plugins.sbt file:

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

And enable the plugin in your build.sbt file:

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

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

You can find additional details on the sbt-javaagent GitHub repo.

You can monitor up to three microservices
for free with Kamon APM