Installation on a Plain Application #

This guide is an “extended” version of the official Get Started steps for manual instrumentation, but here we dive a little bit more into what is being achieved in each step. The general idea stays the same as in the official guide, there are three simple steps to follow:

1. Install Kamon.
2. Verify the Installation.
3. Install Reporters.

Install Kamon #

Add the Core Dependency #

First of all, add the kamon-core dependency using your build system of choice. The core dependency contains all the Context Propagation, Metrics and Tracing APIs, but does not include any instrumentation. Here is how it would look like in your build:

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

    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-core_2.13</artifactId>
      <version>2.5.9</version>
    </dependency>

implementation 'io.kamon:kamon-core_2.13:2.5.9'

The core dependency is available for Java 8+ and published for Scala 2.11, 2.12 and 2.13. If you are not familiar with the Scala version suffix then just pick the greatest Scala version available.

Include the Status Page #

This is not really necessary, but it is really helpful to have the Status Page module installed so that the installation can be verified and in general, have an idea of how is Kamon doing. To add the module, just add the dependency to your build system:

libraryDependencies += "io.kamon" %% "kamon-status-page" % "2.5.9"

    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-status-page_2.13</artifactId>
      <version>2.5.9</version>
    </dependency>

implementation 'io.kamon:kamon-status-page_2.13:2.5.9'

Initializing Kamon #

The last step is to initialize Kamon, which is just about calling Kamon.init() as the very first thing when your main method is invoked:

object Start extends App {
  Kamon.init()

  // Your application code goes here
}

fun main(args: Array<String>) {
  Kamon.init()

  // Your application code goes here
}

  public static void main(String[] args) {
    Kamon.init();

    // Your application code goes here
  }

The initialization process find all modules available on the classpath and initialize them, but since the bundle is not available in the classpath it will not attach the instrumentation agent.

Verify the Installation #

Next time you start your application, Kamon should start the Status Page module included in the previous step, which provides a very convenient way to figure out whether everything is in place or not: just got to localhost:5266 on your browser and something like this should show up:

The important bit here is to ensure that modules are loaded and instrumentation is active. As you start adding more and more metrics modules and custom telemetry to Kamon, you will probably be coming back to this page to verify that all is working as expected.

Install Reporters #

At this point, the only thing you are missing is to install some reporters that will take the metrics and trace data collected by Kamon into an external system. Adding a reporter is just about adding the appropriate dependency to your build. For example, if you wanted to add the Kamon APM reporter to your build, just add the appropriate dependency:

libraryDependencies += "io.kamon" %% "kamon-apm-reporter" % "2.5.9"

    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-apm-reporter_2.13</artifactId>
      <version>2.5.9</version>
    </dependency>

implementation 'io.kamon:kamon-apm-reporter_2.13:2.5.9'

And that is all, Kamon will automatically pick up the module from the classpath and initialize it during startup! Head over to the Reporters Section to see all available reporters, including the ones for Prometheus, Zipkin, InfluxDB, Datadog and several more!