Check out the New Service Map! Check out the all-new Kamon APM Service Map!

Play Framework Instrumentation #

The Play Framework instrumentation automatically enables Context propagation and distributed tracing for both incoming and outgoing requests processed by Play, as well as lower level HTTP server metrics. The gist of the features provided by the instrumentation is:

  1. Context will be automatically propagated using HTTP headers.
  2. Client and Server HTTP request Spans will be automatically created and propagated, meaning that besides tracing you will also get HTTP endpoint metrics via the span.processing-time metric.
  3. Lower level HTTP server metrics will be collected for the HTTP server side.

The instrumentation will work out of the box with both the default Akka HTTP server or the Netty HTTP server, as well as instrument HTTP client requests made with the WSClient for Play Framework 2.6 and 2.7.

Just as a reminder, you will need to use the SBT Kanela Runner for Play Framework applications if you plan to use Kamon while running on development mode. Please refer to the Get Started guide if you need help with the setup.

Below, you will find a more detailed descriptions of each feature and relevant configuration settings in case you want to customize the behavior, but you don’t need to learn any of it start using the instrumentation! Just start to your application with the instrumentation agent and you are good to go.

Context Propagation #

The client and server instrumentations build on top of lower level building blocks provided by Kamon, such as the HTTP Propagation Channels and the common HTTP Client and Server instrumentation, you don’t need to do anything special to get them to work other than starting your application with the instrumentation agent. In the following sections we will put together all bits and pieces that can be configured for the Akka HTTP instrumentation in case you want to know what is happening under the hood and how to modify the instrumentation behavior.

Controlling Propagation #

The instrumentation will automatically read/write Kamon’s Context from/tp HTTP headers in all HTTP requests and set that Context as current while requests are being processed, enabling higher level features like distributed tracing. If you want to change the propagation channel or completely disable Context propagation you can use the propagation settings below:

kamon.instrumentation.play.http {
  server {
    propagation {
      enabled = yes
      channel = default
    }
  }

  client {
    propagation {
      enabled = yes
      channel = default
    }
  }
}

Please note that without Context propagation Kamon will not be able to properly join distributed traces!

Custom Tag Mappings #

By default, Kamon will use the context-tags HTTP header to transport all Context tags, but if you want to configure a specific header to transport one context tag, you can do so by providing a mapping on the HTTP propagation channel:

kamon.propagation.http.default.tags {
  mappings {
    requestID = "X-Request-ID"
  }
}

With the settings above, Kamon will automatically try to turn the contents of the X-Request-ID HTTP header on incoming requests into the requestID Context tag and also write the value of the requestID Context tag (if present) on the X-Request-ID HTTP header for outgoing requests.

Request Tracing #

HTTP Server and Client requests processed by the application will be automatically traced, which in turn means that metrics can (and will) be recorded for the HTTP operations. You can control whether tracing is enabled or not under the tracking section below, as well as controlling whether Span Metrics will be recorded when tracing is enabled:

kamon.instrumentation.play.http {
  server {
    tracing {
      enabled = yes
      span-metrics = on
    }
  }

  client {
    tracing {
      enabled = yes
      span-metrics = on
    }
  }
}

Customizing the Span Tags #

Kamon will automatically add the HTTP URL, method and status code (from the response) as tags to all Spans generated via instrumentation and you can configure how these tags will be added on the client and server sides of the instrumentation by adding one of the following modes to each setting:

  • off will prevent Kamon from adding the tag to Spans.
  • span will add the tag as a Span tag.
  • metric will add the tag as a Span metric tag. Please note that you should not use high cardinality values as metric tags, that’s one of the reasons the URL is only set as a span tag.

Also, it is possible to make Kamon copy tags from the current Context into the HTTP operation Spans by using the from-context section. In the example below we are showing the default settings for the Akka HTTP instrumentation and additionally, we are instructing Kamon to copy the requestID tag as a Span tag for both the client and server side instrumentation.

kamon.instrumentation.play.http {
  server.tracing.tags {
    url = span
    method = metric
    status-code = metric

    from-context {
      requestID = span
    }
  }

  client.tracing.tags {
    url = span
    method = metric
    status-code = metric

    from-context {
      requestID = span
    }
  }
}

HTTP Server Metrics #

As a lower level part of the instrumentation, Kamon will track the performance of the HTTP Server. You can control whether HTTP Server metrics will be recorded or not by using the `` setting:

kamon.instrumentation.play.http {
  server.metrics {
    enabled = yes
  }
}

This feature is enabled by default and will collect the following metrics:

Counts the number of completed requests per status code.

Instruments are tagged with:

  • component: Name of the HTTP Server Library.
  • interface: Name of the interface on which the server is listening.
  • port: Port number on which the HTTP server is listening.
  • http.status_code: Name of the network interface being measured.
Number of requests being processed simultaneously at any point in time.

Instruments are tagged with:

  • component: Name of the HTTP Server Library.
  • interface: Name of the interface on which the server is listening.
  • port: Port number on which the HTTP server is listening.
Request size distribution (including headers and body) for all requests received by the server.

Instruments are tagged with:

  • component: Name of the HTTP Server Library.
  • interface: Name of the interface on which the server is listening.
  • port: Port number on which the HTTP server is listening.
Response size distribution (including headers and body) for all responses served by the server.

Instruments are tagged with:

  • component: Name of the HTTP Server Library.
  • interface: Name of the interface on which the server is listening.
  • port: Port number on which the HTTP server is listening.
Tracks the time elapsed between connection creation and connection close.

Instruments are tagged with:

  • component: Name of the HTTP Server Library.
  • interface: Name of the interface on which the server is listening.
  • port: Port number on which the HTTP server is listening.
Distribution of number of requests handled per connection during their entire lifetime.

Instruments are tagged with:

  • component: Name of the HTTP Server Library.
  • interface: Name of the interface on which the server is listening.
  • port: Port number on which the HTTP server is listening.
Number of open connections.

Instruments are tagged with:

  • component: Name of the HTTP Server Library.
  • interface: Name of the interface on which the server is listening.
  • port: Port number on which the HTTP server is listening.

Manual Installation #

In case you are not using the Kamon Bundle, add the dependency below to your build.


libraryDependencies += "io.kamon" %% "kamon-play" % "2.1.13"



    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-play_2.12</artifactId>
      <version>2.1.13</version>
    </dependency>


implementation 'io.kamon:kamon-play_2.12:2.1.13'

You must start your application with the instrumentation agent for this module to work properly.