A temporary implementation of the Kamon akka-http module.
Scala
Latest commit 27da788 Jan 15, 2017 @pjfanning pjfanning committed with dpsoft akka-http 10.0.1 (#11)

README.md

Kamon akka-http

Gitter Build Status Maven Central

An early implementation of the Kamon Akka-Http module.

This module is marked as experimental, which means that is in early access mode. We hope to can improve it based on your suggestions and feedback.


Kamon Akka Http module provides bytecode instrumentation to gather metrics and perform automatic TraceContext propagation on your behalf, both on the client and server side.

This WIP currently supports:

  • Traces in the server side and allow configure the X-Trace-Context in order to pass into the current request.
  • HttpServerMetrics that gather metrics with status code and categories + request-active and connection-open (as your snippet)
  • Segments for client-side requests

Get started

Configure

The artifact is available on Maven Central.

  "io.kamon" %% "kamon-akka-http-experimental" % "0.6.2"

The following is an example of a configuration to provide metrics to a server, such as Statsd.

kamon {
  metric {
    filters {
      trace.includes = [ "**" ]
    }
  }

  subscriptions {
    trace                = [ "**" ]
    trace-segment        = [ "**" ]
    akka-http-server     = [ "**" ]
  }
}

You can also provide some settings to this module. Currently the default config is:

kamon {
  akka-http {

    # Header name used when propagating the `TraceContext.token` value across applications.
    trace-token-header-name = "X-Trace-Token"

    # When set to true, Kamon will automatically set and propogate the `TraceContext.token` value.
    automatic-trace-token-propagation = true

    # Fully qualified name of the implementation of kamon.akka.http.AkkaHttpNameGenerator that will be used for assigning names
    # to traces and client http segments.
    name-generator = kamon.akka.http.DefaultNameGenerator

    client {
      # Strategy used for automatic trace segment generation when issue requests with akka-http-client. The possible values
      # are: request-level and host-level (Not implemented yet!).
      instrumentation-level = request-level
    }
  }
}

A better explanation is provided in the kamon-akka-http's reference.conf.

Run

kamon-akka-http module require you to start your application using the AspectJ Weaver Agent. Kamon will warn you at startup if you failed to do so.

To achieve it quickly you can use the sbt-aspectj-runner plugin.

Enjoy!

Examples

Coming soon!

Naming HTTP Client Segments

By default, the name generator bundled with the kamon-akka-http module will use the Host header available in the request to assign a name to the automatically generated segment. Currently, the only way to override that name would be to provide your own implementation of kamon.akka.http.AkkaHttpNameGenerator which is used to assign names both on the server and client sides of our instrumentation.

Backlog

  • Connection-Level Client-Side API
  • Host-Level Client-Side API support
  • Take some ideas from spray-kamon-metrics