allow arbitrary header names for automatic broadcast string keys, fixes #505issue#505/arbitrary-header-names-for-string-keys

1 files changed, 18 insertions, 1 deletions

diff --git a/kamon-core/src/main/resources/reference.conf b/kamon-core/src/main/resources/reference.conf
index 2d37780d..659114ca 100644
--- a/kamon-core/src/main/resources/reference.conf
+++ b/kamon-core/src/main/resources/reference.conf
@@ -150,7 +150,24 @@ kamon {
       # Size of the encoding buffer for the Binary Codec.
       binary-buffer-size = 256
 
-      string-keys = [ ]
+      # Declarative definition of broadcast context keys with type Option[String]. The setting key represents the actual
+      # key name and the value is the HTTP header name to be used to encode/decode the context key. The key name will
+      # be used when coding for binary transport. The most common use case for string keys is effortless propagation of
+      # correlation keys or request related data (locale, user ID, etc). E.g. if wanting to propagate a "X-Request-ID"
+      # header this config should suffice:
+      #
+      # kamon.context.codecs.string-keys {
+      #   request-id = "X-Request-ID"
+      # }
+      #
+      # If the application must read this context key they can define key with a matching name and read the value from
+      # the context:
+      #   val requestIDKey = Key.broadcastString("request-id") // Do this only once, keep a reference.
+      #   val requestID = Kamon.currentContext().get(requestIDKey)
+      #
+      string-keys {
+
+      }
 
       # Codecs to be used when propagating a Context through a HTTP Headers transport.
       http-headers-keys {