Today we are announcing Kamon 1.1.0 with a couple bugfixes and a small but important improvement on context propagation, plus several minor updates on other modules that sort of went under the table for Akka, Akka Remote, Akka HTTP, Play Framework, Http4s and our sbt-aspectj-runner plugin.

Context Propagation Improvements

Now you must specify header names for broadcast string keys. In case you didn’t know about it just yet, in Kamon 1.0.0 you are able to use the kamon.context.codecs.string-keys setting to define arbitrary context key names for which you will get automatically generated codecs for both HTTP and Binary propagation. This was nice and useful, but the automatically generated header name for HTTP (something like X-KamonContext-$key) wasn’t really the most friendly thing ever and didn’t allow for cases when you need to follow conventions dictated before Kamon was put in place. You could still achieve that by implementing your own HTTP codec for your context key, but that’s an overkill for most cases where you just need to pass arbitrary strings around. Starting on this release the codecs for string-keys will require you to specify both the key name AND the header name to be used. For example:

kamon.context.codecs.string-keys {
  request-id = "X-Request-ID"
}

The above configuration will ensure that the X-Request-ID header is packed/unpacked into a broadcast string key in the context without any code changes. If you wish to read this key in your service code just define a broadcast string Key matching the config-provided key name and get the value from a Context:

// Do this only once, keep a reference
val requestIDKey = Key.broadcastString("request-id")

val requestID = Kamon.currentContext().get(requestIDKey)

Why is this important?

One of the most used features in Kamon is the ability to propagate request or user identifiers across thread/process boundaries and that has been available for quite some time (even before 1.0), but this little change unlocks something that might not be so obvious but of great value: you can now propagate arbitrary context used by sidecars (think Linkerd/Envoy) without having to touch your application code, just configuration! This is a quite exciting feature and requires a dedicated explanation, blog post coming! But to give you an idea, adding this configuration should be enough to propagate all Linkerd Context Headers, regardless of whether you are using Play Framework, Akka HTTP, Http4s or any other supported HTTP toolkit.

kamon.context.codecs.string-keys {
  l5d-ctx-dtab = "l5d-ctx-dtab"
  l5d-ctx-deadline = "l5d-ctx-deadline"
  l5d-ctx-trace = "l5d-ctx-trace"
}

Environment Tags

We now have a place to put environment-specific tags. Think of tags likeenv=staging or region=us-east-1 that should be applied to all data extracted from Kamon. Now, all these tags can be configured in the kamon.environment.tags setting, for example:

kamon.environment.tags {
  env = "staging"
  region = "us-east-1"
}

Please note that these tags are only informative from the Kamon core perspective, it’s a well known place to put these tags (contrary to Kamon 0.6.x where each reporting module had its way to do this). Each reporting module should read and publish them if needed and in the following days we will start adding them to the available modules.

New Features

  • #505 Arbitrary header names for broadcast string keys when propagating over HTTP. Contributed by @ivantopo in #509.
  • #510 Allow environment tags. Contributed by @ivantopo in #515.

Fixes:

  • The trace reporters ticker was always being restarted on calls to Kamon.reconfigure(...) due to a copy/paste mistake, reported and fixed by @briantopping in #504
  • #513: Calls to tagMetric on non-sampled spans would not apply the tag. Fixed by @ivantopo in #516.

Other Updates You Might Have Missed

kamon-akka-http 1.1.0

Version 1.1.0 comes with a new kamon.akka-http.add-http-status-code-as-metric-tag setting that, as you might have guessed, allows you to add the HTTP status code as a metric tag for the span.processing-time metrics generated out of HTTP server/client spans. This was contributed by @ptrlaszlo in #28.

kamon-http4s 1.0.2

Version 1.0.2 fixes context propagation when using the HTTP client side of Https4s. This was fixed by @dpsoft in 74457a16. Thanks to @aggenebbisj for reporting the issue and helping around!

kamon-play 1.0.1

Version 1.0.1 was published with a small fix: the span.kind=server tag was not being applied to HTTP server spans by default. This was fixed by @dpsoft in 3732c9a

kamon-akka 1.0.1

Version 1.0.1 has a fix for a NPE raised when akka.actor.serialize-messages=on. This was only affecting Akka 2.5 and there are more details on the related Github issue. Fixed by @vantopo in a044c450. Thanks to @martijnblankestijn for reporting the issue!

kamon-akka-remote 1.0.1

A couple issues were fixed on version 1.0.1:

  • The Context would be lost when sending messages to a Shard that has not been created yet due to messages being enqueued in a MessageBufferMap until the shard was ready. Fixed on #10 by @lustefaniak. Thanks a lot!
  • There were some test leftovers on our reference.conf file that would make Akka start logging to stdout as reported in #11. Fixed on 2cf47d1 by @ivantopo.

sbt-aspectj-runner 1.1.0

Version 1.1.0 brings proper support for Play Framework 2.6 (we thought 1.0.4 was working properly with it, but it wasn’t).

As a side effect of that, we removed the older code that worked for Play 2.4/2.5 because of issues with cross publishing for SBT 0.13/1.0 when one of the sub projects shouldn’t be cross built. Surely there is a way to do it, but there was no need for such hassle as people could just continue to use the older version for Play 2.4/2.5.

The published plugins are:

  • sbt-aspectj-runner as the base plugin, used for any “regular” applications.
  • sbt-aspectj-runner-play-2.6 for running Play Framework 2.6 applications.

That’s it for now, getting back to bake some more awesomeness!