Documentation

What is Kamon?

Kamon is a monitoring toolkit for applications running on the JVM. It gives you Metrics, Tracing and Context Propagation APIs without locking you to any specific vendor. All Kamon APIs are completely decoupled from the services that can receive the data, be it StatsD, Prometheus, Kamino, Datadog, Zipkin, Jaeger or any other supported reporter, with Kamon you instrument your application once and report anywhere you want.

Start using Kamon

There are a number of Recipes that can help you get the exact results you are looking for but, if you just want a quick start then follow these steps:

Add the Library

All Kamon modules are available through Maven Central and you just need to add them as a dependency to your project. The details on how to do this will differ depending on your dependency management tool of choice, but usually just by knowing that our group id is io.kamon and our artifacts are named after the module name you are good to go. To get kamon-core in your project, try one of these:

libraryDependencies += "io.kamon" %% "kamon-core" % "1.0.0-RC4"

// Optional Dependencies
libraryDependencies += "io.kamon" %% "kamon-prometheus" % "1.0.0-RC4"
libraryDependencies += "io.kamon" %% "kamon-zipkin" % "1.0.0-RC4-3e433d8ae40a05435e81f37cb9347c5ec99756c1"
  <dependencies>
    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-core_2.12</artifactId>
      <version>1.0.0</version>
    </dependency>

    <!-- Optional Dependencies -->
    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-prometheus_2.12</artifactId>
      <version>1.0.0</version>
    </dependency>
    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-zipkin_2.12</artifactId>
      <version>1.0.0</version>
    </dependency>
  </dependencies>
dependencies {
  compile 'io.kamon:kamon-core_2.12:1.0.0'
  compile 'io.kamon:kamon-prometheus_2.12:1.0.0'
  compile 'io.kamon:kamon-zipkin_2.12:1.0.0'
}

Starting with Kamon 1.0.0 we only support Java 8+. All modules are published for Scala 2.10, 2.11 and 2.12. 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.

Also, we publish snapshots to our Bintray Snapshots Repository when trying out new concepts or releasing test versions of our modules, keep that in mind if you want to be on the bleeding edge. There you can find instructions for Maven and Gradle; for SBT add resolvers += Resolver.bintrayRepo("kamon-io", "snapshots") to your build.sbt file and your done.

Record Metrics

The kamon.Kamon companion object gives you everything you need to create metrics Instruments and start measuring your application’s behavior:

  val myHistogram = Kamon.histogram("my.histogram")
  val myCounter = Kamon.counter("my.counter")
  val myTaggedCounter = Kamon.counter("my.tagged.counter").refine("env" -> "test")

  myHistogram.record(42)
  myHistogram.record(50)
  myCounter.increment()
  myTaggedCounter.increment()
    final Histogram myHistogram = Kamon.histogram("my.histogram");
    final Counter myCounter = Kamon.counter("my.counter");
    final Counter myTaggedCounter = Kamon.counter("my.tagged.counter").refine("env", "test");

    myHistogram.record(42);
    myHistogram.record(50);
    myCounter.increment();

You can simply use the instruments returned by Kamon or you can .refine(...) them to get specialized instruments with the specified tags.

Record Spans

Again, all you need is in the kamon.Kamon companion object, although, you are most likely never going to start a Span by yourself but rather use the provided instrumention for toolkits and frameworks.

  val span = Kamon.buildSpan("my.operation").start()
  // Do some work here
  span
    .tag("key", "value")
    .finish()
    final Span span = Kamon.buildSpan("my.operation").start();
    // Do some work here
    span
      .tag("key", "value")
      .finish();

Spans can be tagged with Strings, Longs and Booleans. Also, Kamon will automatically track metrics for all your Spans and you can customize that behavior by using span.tagMetric(...) on any Span.

Start Reporting your Data

Reporters take care of sending the Metrics and Tracing data to your backend of choice. Check the Reporters section for all available reporters.

  Kamon.addReporter(new PrometheusReporter())
  Kamon.addReporter(new ZipkinReporter())
    Kamon.addReporter(new PrometheusReporter());
    Kamon.addReporter(new ZipkinReporter());

What’s Next?

That’s a basic setup that can get you reporting metrics and trace data, but there is so much more that you can do with Kamon. Follow the Recipes and have fun!