In most situations, you won’t need to do anything special to set up the Kanela agent other than following the instructions
in the Installation Guides. In a guided installation either the call to
Kamon.init() or the SBT
plugins will take care of attaching the Kanela agent at runtime.
Nevertheless, sometimes things get weird and you need alternative options. This how to summarizes all the ways in which you could start your applications with the Kanela agent. Let’s get to it!
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 below:
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 below when:
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
fork in run := true) or not. To get it working add these lines to your
addSbtPlugin("io.kamon" % "sbt-kanela-runner" % "2.0.12")
That’s it! Next time your application starts, instrumentation will be enabled.
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:
// For Play Framework 2.8.8 addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.8" % "2.0.12") // OR for Play Framework <= 2.8.7 addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.8" % "2.0.10")
addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.7" % "2.0.12")
addSbtPlugin("io.kamon" % "sbt-kanela-runner-play-2.6" % "2.0.12")
The runner brings the sbt-javaagent dependency with it, but it requires
you to active it explicitly by calling
.enablePlugin(JavaAgent) on the right project instance in your
it should look like this:
lazy val root = (project in file(".")).enablePlugins(PlayScala, JavaAgent)
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
addSbtPlugin("com.lightbend.sbt" % "sbt-javaagent" % "0.1.6")
And enable the plugin in your
lazy val root = (project in file(".")) .enablePlugins(JavaAppPackaging, JavaAgent) javaAgents += "io.kamon" % "kanela-agent" % "1.0.11"
You can find additional details on the sbt-javaagent GitHub repo.