cleanup the context propagation section on the configuration file

3 files changed, 45 insertions, 61 deletions

diff --git a/kamon-core-tests/src/test/scala/kamon/trace/B3SpanCodecSpec.scala b/kamon-core-tests/src/test/scala/kamon/trace/B3SpanPropagationSpec.scala
index 73de22bb..5b912b92 100644
--- a/kamon-core-tests/src/test/scala/kamon/trace/B3SpanCodecSpec.scala
+++ b/kamon-core-tests/src/test/scala/kamon/trace/B3SpanPropagationSpec.scala
@@ -25,8 +25,8 @@ import org.scalatest.{Matchers, OptionValues, WordSpecLike}
 import scala.collection.mutable
 
 
-class B3SpanCodecSpec extends WordSpecLike with Matchers with OptionValues with SpanBuilding {
-  val b3Propagation = SpanCodec.B3()
+class B3SpanPropagationSpec extends WordSpecLike with Matchers with OptionValues with SpanBuilding {
+  val b3Propagation = SpanPropagation.B3()
 
   "The B3 Span propagation for HTTP" should {
     "write the Span data into headers" in {
@@ -61,7 +61,7 @@ class B3SpanCodecSpec extends WordSpecLike with Matchers with OptionValues with
         "X-B3-ParentSpanId" -> "2222",
         "X-B3-SpanId" -> "4321",
         "X-B3-Sampled" -> "1",
-        "X-B3-Extra-Baggage" -> "some=baggage;more=baggage",
+        "X-B3-Extra-Baggage" -> "some=baggage;more=baggage"
       )
 
       val spanContext = b3Propagation.read(headerReaderFromMap(headersMap), Context.Empty).get(Span.ContextKey).context()
diff --git a/kamon-core/src/main/resources/reference.conf b/kamon-core/src/main/resources/reference.conf
index a4a7871e..eb374455 100644
--- a/kamon-core/src/main/resources/reference.conf
+++ b/kamon-core/src/main/resources/reference.conf
@@ -150,57 +150,17 @@ kamon {
     }
   }
 
-
-  context {
-
-    # Codecs are used to encode/decode Context keys when a Context must be propagated either through HTTP headers or
-    # Binary transports. Only broadcast keys configured bellow will be processed by the context Codec. The FQCN of
-    # the appropriate Codecs for each key must be provided, otherwise keys will be ignored.
-    #
-    codecs {
-
-      # Size of the encoding buffer for the Binary Codec.
-      binary-buffer-size = 256
-
-      # 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 {
-        //span = "kamon.trace.SpanCodec$B3"
-      }
-
-      # Codecs to be used when propagating a Context through a Binary transport.
-      binary-keys {
-        //span = "kamon.trace.SpanCodec$Colfer"
-      }
-    }
-  }
-
-
   propagation {
+
     http {
 
       # Default HTTP propagation. Unless specified otherwise, all instrumentation will use the configuration on
       # this section for HTTP context propagation.
       #
       default {
+
+        # Configures how context tags will be propagated over HTTP headers.
+        #
         tags {
 
           # Header name used to encode context tags.
@@ -225,18 +185,20 @@ kamon {
           }
         }
 
+        # Configure which entries should be read from incoming HTTP requests and writen to outgoing HTTP requests.
+        #
         entries {
 
-          # Specify mappings between Context keys and the Http.EntryReader implementation in charge of reading them
-          # from the incoming HTTP request into the Context.
+          # Specify mappings between Context keys and the Propagation.EntryReader[HeaderReader] implementation in charge
+          # of reading them from the incoming HTTP request into the Context.
           incoming {
-            #span = "something"
+            span = "kamon.trace.SpanPropagation$B3"
           }
 
-          # Specify mappings betwen Context keys and the Http.EntryWriter implementation in charge of writing them
-          # on the outgoing HTTP requests.
+          # Specify mappings betwen Context keys and the Propagation.EntryWriter[HeaderWriter] implementation in charge
+          # of writing them to outgoing HTTP requests.
           outgoing {
-
+            span = "kamon.trace.SpanPropagation$B3"
           }
         }
       }
@@ -248,18 +210,21 @@ kamon {
       # this section for HTTP context propagation.
       #
       default {
+
+        # Configure which entries should be read from incoming messages and writen to outgoing messages.
+        #
         entries {
 
-          # Specify mappings between Context keys and the Http.EntryReader implementation in charge of reading them
-          # from the incoming HTTP request into the Context.
+          # Specify mappings between Context keys and the Propagation.EntryReader[ByteStreamReader] implementation in
+          # charge of reading them from the incoming messages into the Context.
           incoming {
-            #span = "something"
+            span = "kamon.trace.SpanPropagation$Colfer"
           }
 
-          # Specify mappings betwen Context keys and the Http.EntryWriter implementation in charge of writing them
-          # on the outgoing HTTP requests.
+          # Specify mappings betwen Context keys and the Propagation.EntryWriter[ByteStreamWriter] implementation in
+          # charge of writing them on the outgoing messages.
           outgoing {
-
+            span = "kamon.trace.SpanPropagation$Colfer"
           }
         }
       }
diff --git a/kamon-core/src/main/scala/kamon/trace/SpanCodec.scala b/kamon-core/src/main/scala/kamon/trace/SpanPropagation.scala
index 63f8e1b0..b83a5ade 100644
--- a/kamon-core/src/main/scala/kamon/trace/SpanCodec.scala
+++ b/kamon-core/src/main/scala/kamon/trace/SpanPropagation.scala
@@ -26,8 +26,15 @@ import kamon.context.HttpPropagation.{HeaderReader, HeaderWriter}
 import kamon.trace.SpanContext.SamplingDecision
 
 
-object SpanCodec {
-
+/**
+  * Propagation mechanisms for Kamon's Span data to and from HTTP and Binary mediums.
+  */
+object SpanPropagation {
+
+  /**
+    * Reads and Writes a Span instance using the B3 propagation format. The specification and semantics of the B3
+    * Propagation protocol can be found here: https://github.com/openzipkin/b3-propagation
+    */
   class B3 extends Propagation.EntryReader[HeaderReader] with Propagation.EntryWriter[HeaderWriter] {
     import B3.Headers
 
@@ -102,6 +109,18 @@ object SpanCodec {
   }
 
 
+  /**
+    * Defines a bare bones binary context propagation that uses Colfer [1] as the serialization library. The Schema
+    * for the Span data is simply defined as:
+    *
+    * type Span struct {
+    *   traceID binary
+    *   spanID binary
+    *   parentID binary
+    *   samplingDecision uint8
+    * }
+    *
+    */
   class Colfer extends Propagation.EntryReader[ByteStreamReader] with Propagation.EntryWriter[ByteStreamWriter] {
     val emptyBuffer = ByteBuffer.allocate(0)