You are viewing documentation for an outdated version. Do you wish to see documentation for the latest version?

Getting Started with Kamon #

Welcome to the Kamon Community! This guide will help you install the Kamon libraries and the instrumentation agent in your application. Long story short, you need to go through 3 steps:

1. Add the Kamon libraries.
2. Start modules you want.
3. Enable the bytecode instrumentation.

Adding Libraries #

Add the kamon-core dependency using your build system of choice. This dependency contains all the context propagation, metrics and distributed tracing APIs required to instrument any application running on the JVM.

libraryDependencies += "io.kamon" %% "kamon-core" % "1.1.3"

// Additional Dependencies
libraryDependencies += "io.kamon" %% "kamon-akka-2.5" % "1.1.2"
libraryDependencies += "io.kamon" %% "kamon-prometheus" % "1.1.1"
libraryDependencies += "io.kamon" %% "kamon-zipkin" % "1.0.0"

dependencies {
  compile "io.kamon:kamon-core_2.12:1.2.0-M1"

  // Reporter Dependencies
  compile "io.kamon:kamon-akka-2.5_2.12:1.1.2"
  compile "io.kamon:kamon-prometheus_2.12:1.1.1"
  compile "io.kamon:kamon-zipkin_2.12:1.0.0"
}

  <dependencies>
    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-core_2.12</artifactId>
      <version>1.1.3</version>
    </dependency>

    <!-- Reporter Dependencies -->
    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-akka-2.5_2.12</artifactId>
      <version>1.1.2</version>
    </dependency>
    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-prometheus_2.12</artifactId>
      <version>1.1.1</version>
    </dependency>
    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-zipkin_2.12</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>

Kamon is available for Java 8+. All modules are published for Scala 2.10, 2.11 and 2.12 (when possible). If you are not familiar with the Scala version suffix then just pick the greatest Scala version available, currently 2.12, as shown in the Maven/Gradle examples above.

Additional Libraries #

Besides the core library, you will need to bring two additional groups of dependencies: first, the instrumentation modules that help you gather metrics and trace data from your application like the Akka and Play instrumentation or the System Metrics module, and second, the reporting modules that let you export that data to external systems like Prometheus, Zipkin and so on. You can find a list of all modules in our instrumentation section.

Loading Modules #

During your application startup procedure you must call Kamon.loadModules(). This will make Kamon detect all modules available in the classpath and start them appropriately.

object Start extends App {
  Kamon.addReporter(new PrometheusReporter())
  Kamon.addReporter(new ZipkinReporter())
}

fun main(args: Array<String>) {
  Kamon.addReporter(PrometheusReporter())
  Kamon.addReporter(ZipkinReporter())
}

  public static void main(String[] args) {
    Kamon.addReporter(new PrometheusReporter());
    Kamon.addReporter(new ZipkinReporter());
  }

Take a look at the [configuration section][configuration] if you need finer control over what modules are loaded during startup.

Enabling Instrumentation #

The bytecode instrumentation is powered by AspectJ, all you need to do is add the -javaagent JVM startup parameter pointing to the aspectjweaver.jar file from the latest AspectJ distribution as shown below:

java -javaagent:/path/to/aspectjweaver.jar ...

Depending on your build system and tools there might be additional or special steps, please refer to the agent setup section for instructions specific to your environment.