Skip to content

v1.1.0 - Context Propagation Improvements, Environment Tags and Fixes
Compare
Choose a tag to compare
@ivantopo ivantopo released this 26 Feb 14:41
· 2799 commits to master since this release
v1.1.0
4cee78c

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 environemnt 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.
Assets 2
Loading