document and reorganize reference settings (#1)

Author: ivantopo

src/main/resources/reference.conf

@@ -16,50 +16,52 @@ kamon {
 
       # Max packet size for UDP metrics data sent to Datadog.
       max-packet-size = 1024 bytes
-
       measurement-formatter = "default"
-
       packetbuffer = "default"
-
     }
 
     #
-    # Settings relevant to the DatadogAPIReporter
+    # Settings relevant to the DatadogSpanReporter
     #
-    http {
+    trace {
 
-      api-url = "https://app.datadoghq.com/api/v1/series"
-
-
-      # Datadog API key to use to send metrics to datadog directly over HTTPS.
-      # If this is not set, metrics are sent as statsd packets over UDP to dogstatsd.
-      api-key = ""
+      # Default to agent URL (https://docs.datadoghq.com/api/?lang=python#tracing)
+      api-url = "http://localhost:8126/v0.4/traces"
 
-      using-agent = false
+      # FQCN of the "kamon.datadog.KamonDataDogTranslator" implementation that will convert Kamon Spans into Datadog
+      # Spans, or "defult" to use the built-in translator.
+      translator = "default"
 
+      # HTTP client timeout settings:
+      #   - connect-timeout: how long to wait for an HTTP connection to establish before failing the request.
+      #   - read-timeout: how long to wait for a read IO operation to complete before failing the request.
+      #   - write-timeout: how long to wait for a write IO operation to complete before failing the request.
+      #
       connect-timeout = 5 seconds
       read-timeout = 5 seconds
-      request-timeout = 5 seconds
+      write-timeout = 5 seconds
     }
 
-
     #
-    # Settings relevant to the DatadogSpanReporter
+    # Settings relevant to the DatadogAPIReporter
     #
-    trace.http {
-
-      # Default to agent URL (https://docs.datadoghq.com/api/?lang=python#tracing)
-      api-url = "http://localhost:8126/v0.4/traces"
-
-      api-key = ${kamon.datadog.http.api-key}
+    api {
 
-      using-agent = true
+      # API endpoint to which metrics time series data will be posted.
+      api-url = "https://app.datadoghq.com/api/v1/series"
 
-      connect-timeout = ${kamon.datadog.http.connect-timeout}
-      read-timeout = ${kamon.datadog.http.read-timeout}
-      request-timeout = ${kamon.datadog.http.request-timeout}
+      # Datadog API key to use to send metrics to Datadog directly over HTTPS. The API key will be combined with the
+      # API URL to get the complete endpoint use for posting time series to Datadog.
+      api-key = ""
 
-      translator = "default"
+      # HTTP client timeout settings:
+      #   - connect-timeout: how long to wait for an HTTP connection to establish before failing the request.
+      #   - read-timeout: how long to wait for a read IO operation to complete before failing the request.
+      #   - write-timeout: how long to wait for a write IO operation to complete before failing the request.
+      #
+      connect-timeout = 5 seconds
+      read-timeout = 5 seconds
+      write-timeout = 5 seconds
     }
 
 
@@ -84,8 +86,6 @@ kamon {
         excludes = []
       }
     }
-
-
   }
 
   modules {
@@ -96,19 +96,20 @@ kamon {
       factory = "kamon.datadog.DatadogAgentReporterFactory"
     }
 
+    datadog-trace-agent {
+      enabled = true
+      name = "DatadogSpanReporter"
+      description = "Datadog Span reporter"
+      factory = "kamon.datadog.DatadogSpanReporterFactory"
+    }
+
     datadog-api {
       enabled = false
       name = "DatadogHttp"
       description = "Datadog HTTP reporter"
       factory = "kamon.datadog.DatadogAPIReporterFactory"
     }
-
-    datadog-span-reporter {
-      enabled = true
-      name = "DatadogSpanReporter"
-      description = "Datadog Span reporter"
-      factory = "kamon.datadog.DatadogSpanReporterFactory"
-    }
   }
-
 }
+
+

src/main/scala/kamon/datadog/DatadogAPIReporter.scala

@@ -37,7 +37,7 @@ import scala.util.{ Failure, Success }
 class DatadogAPIReporterFactory extends ModuleFactory {
   override def create(settings: ModuleFactory.Settings): DatadogAPIReporter = {
     val config = DatadogAPIReporter.readConfiguration(settings.config)
-    new DatadogAPIReporter(config, new HttpClient(config.httpConfig))
+    new DatadogAPIReporter(config, new HttpClient(config.httpConfig, usingAgent = false))
   }
 }
 
@@ -59,7 +59,7 @@ class DatadogAPIReporter(@volatile private var configuration: Configuration, @vo
   override def reconfigure(config: Config): Unit = {
     val newConfiguration = readConfiguration(config)
     configuration = newConfiguration
-    httpClient = new HttpClient(configuration.httpConfig)
+    httpClient = new HttpClient(configuration.httpConfig, usingAgent = false)
   }
 
   override def reportPeriodSnapshot(snapshot: PeriodSnapshot): Unit = {
@@ -158,7 +158,7 @@ private object DatadogAPIReporter {
   def readConfiguration(config: Config): Configuration = {
     val datadogConfig = config.getConfig("kamon.datadog")
     Configuration(
-      datadogConfig.getConfig("http"),
+      datadogConfig.getConfig("api"),
       timeUnit = readTimeUnit(datadogConfig.getString("time-unit")),
       informationUnit = readInformationUnit(datadogConfig.getString("information-unit")),
       // Remove the "host" tag since it gets added to the datadog payload separately

src/main/scala/kamon/datadog/DatadogAgentReporter.scala

@@ -196,7 +196,8 @@ object DatadogAgentReporter {
       }
     }
 
-    private def fitsOnBuffer(data: String): Boolean = (buffer.length + data.length) <= maxPacketSizeInBytes
+    private def fitsOnBuffer(data: String): Boolean =
+      (buffer.length + data.length) <= maxPacketSizeInBytes
 
     private def flushToUDP(data: String): Unit = {
       val channel = DatagramChannel.open()

src/main/scala/kamon/datadog/DatadogSpanReporter.scala

@@ -4,13 +4,13 @@ import java.time.Duration
 
 import com.typesafe.config.Config
 import kamon.trace.Span
-import kamon.{ClassLoading, Kamon}
+import kamon.{ ClassLoading, Kamon }
 import kamon.datadog.DatadogSpanReporter.Configuration
-import kamon.module.{ModuleFactory, SpanReporter}
-import kamon.tag.{Lookups, Tag, TagSet}
-import kamon.util.{EnvironmentTags, Filter}
+import kamon.module.{ ModuleFactory, SpanReporter }
+import kamon.tag.{ Lookups, Tag, TagSet }
+import kamon.util.{ EnvironmentTags, Filter }
 import org.slf4j.LoggerFactory
-import play.api.libs.json.{JsObject, Json}
+import play.api.libs.json.{ JsObject, Json }
 
 trait KamonDataDogTranslator {
   def translate(span: Span.Finished, additionalTags: TagSet, tagFilter: Filter): DdSpan
@@ -22,9 +22,10 @@ object KamonDataDogTranslatorDefault extends KamonDataDogTranslator {
     val spanId = BigInt(span.id.string, 16)
 
     val parentId = if (span.parentId.isEmpty) None else Some(BigInt(span.parentId.string, 16))
-
-    val name = span.tags.get(Lookups.option("component"))
+    val name = span.metricTags
+      .get(Lookups.option("component"))
       .getOrElse("kamon.trace")
+
     val resource = span.operationName
     val service = Kamon.environment.service
     val from = span.from
@@ -34,7 +35,7 @@ object KamonDataDogTranslatorDefault extends KamonDataDogTranslator {
     val tags = (span.tags.all() ++ span.metricTags.all() ++ additionalTags.all()).map { t =>
       t.key -> Tag.unwrapValue(t).toString
     }
-    val meta = (marks ++ tags).filterKeys(tagFilter.accept(_))
+    val meta = (marks ++ tags).filterKeys(tagFilter.accept(_)).toMap
     new DdSpan(traceId, spanId, parentId, name, resource, service, "custom", start, duration, meta, span.hasError)
 
   }
@@ -45,11 +46,11 @@ object DatadogSpanReporter {
   case class Configuration(
     translator: KamonDataDogTranslator,
     httpClient: HttpClient,
-    tagFilter: Filter,
-    envTags: TagSet
+    tagFilter:  Filter,
+    envTags:    TagSet
   )
 
-  private[kamon] val httpConfigPath = "kamon.datadog.trace.http"
+  private[kamon] val httpConfigPath = "kamon.datadog.trace"
 
   private[kamon] def getTranslator(config: Config): KamonDataDogTranslator = {
     config.getConfig(httpConfigPath).getString("translator") match {
@@ -62,9 +63,9 @@ object DatadogSpanReporter {
 
     Configuration(
       getTranslator(config),
-      new HttpClient(config.getConfig(DatadogSpanReporter.httpConfigPath)),
+      new HttpClient(config.getConfig(DatadogSpanReporter.httpConfigPath), usingAgent = true),
       Kamon.filter("kamon.datadog.environment-tags.filter"),
-      EnvironmentTags.from(Kamon.environment, config.getConfig("kamon.datadog.environment-tags")).without("service"),
+      EnvironmentTags.from(Kamon.environment, config.getConfig("kamon.datadog.environment-tags")).without("service")
     )
   }
 }

src/main/scala/kamon/datadog/package.scala

@@ -21,18 +21,19 @@ package object datadog {
     }
   }
 
-  private[datadog] case class HttpClient(apiUrl: String, apiKey: String, usingAgent: Boolean, connectTimeout: Duration, readTimeout: Duration, requestTimeout: Duration) {
+  private[datadog] case class HttpClient(apiUrl: String, apiKey: Option[String], usingAgent: Boolean, connectTimeout: Duration,
+                                         readTimeout: Duration, writeTimeout: Duration) {
 
     val httpClient: OkHttpClient = createHttpClient()
 
-    def this(config: Config) = {
+    def this(config: Config, usingAgent: Boolean) = {
       this(
         config.getString("api-url"),
-        config.getString("api-key"),
-        config.getBoolean("using-agent"),
+        if (usingAgent) None else Some(config.getString("api-key")),
+        usingAgent,
         config.getDuration("connect-timeout"),
         config.getDuration("read-timeout"),
-        config.getDuration("request-timeout")
+        config.getDuration("write-timeout")
       )
     }
 
@@ -42,11 +43,9 @@ package object datadog {
 
     def doMethodWithBody(method: String, contentType: String, contentBody: Array[Byte]): Try[String] = {
       val body = RequestBody.create(MediaType.parse(contentType), contentBody)
-      val url = usingAgent match {
-        case true  => apiUrl
-        case false => apiUrl + "?api_key=" + apiKey
-      }
+      val url = apiUrl + apiKey.map(key => "?api_key=" + key).getOrElse("")
       val request = new Request.Builder().url(url).method(method, body).build
+
       doRequest(request) match {
         case Success(response) =>
           val responseBody = response.body().string()
@@ -86,7 +85,7 @@ package object datadog {
       new OkHttpClient.Builder()
         .connectTimeout(connectTimeout.toMillis, TimeUnit.MILLISECONDS)
         .readTimeout(readTimeout.toMillis, TimeUnit.MILLISECONDS)
-        .writeTimeout(requestTimeout.toMillis, TimeUnit.MILLISECONDS)
+        .writeTimeout(writeTimeout.toMillis, TimeUnit.MILLISECONDS)
         .retryOnConnectionFailure(false)
         .build()
     }

src/test/scala/kamon/datadog/DatadogAPIReporterSpec.scala

@@ -21,8 +21,8 @@ class DatadogAPIReporterSpec extends AbstractHttpReporter with Matchers with Rec
 
     "sends counter metrics" in {
       val baseUrl = mockResponse("/test", new MockResponse().setStatus("HTTP/1.1 200 OK"))
-      applyConfig("kamon.datadog.http.api-url = \"" + baseUrl + "\"")
-      applyConfig("kamon.datadog.http.api-key = \"dummy\"")
+      applyConfig("kamon.datadog.api.api-url = \"" + baseUrl + "\"")
+      applyConfig("kamon.datadog.api.api-key = \"dummy\"")
 
       reporter.reconfigure(Kamon.config())
 

src/test/scala/kamon/datadog/DatadogSpanReporterSpec.scala

@@ -1,6 +1,6 @@
 package kamon.datadog
 
-import java.time.{Duration, Instant}
+import java.time.{ Duration, Instant }
 import java.util.concurrent.TimeUnit
 
 import kamon.Kamon
@@ -59,30 +59,30 @@ trait TestData {
     "duration" -> JsNumber(duration.getSeconds * 1000000000 + duration.getNano),
     "name" -> "kamon.trace",
     "meta" -> Json.obj(
-      "env" -> "staging",
+      "env" -> "staging"
     ),
     "error" -> 0,
     "type" -> "custom",
     "start" -> JsNumber(from.getEpochNano),
     "metrics" -> JsObject(Seq(
-       "_sampling_priority_v1" -> JsNumber(1)
+      "_sampling_priority_v1" -> JsNumber(1)
     ))
   )
 
   val spanWithoutParentId = span.copy(parentId = Identifier.Empty)
   val jsonWithoutParentId = json - "parent_id"
 
-  val spanWithError = span.copy(tags = TagSet.of("error", true), hasError=true)
+  val spanWithError = span.copy(tags = TagSet.of("error", true), hasError = true)
 
   val jsonWithError = json ++ Json.obj(
     "meta" -> Json.obj(
       "error" -> "true",
-      "env" -> "staging",
+      "env" -> "staging"
     ),
     "error" -> 1
   )
 
-  val spanWithTags = span.copy(tags =
+  val spanWithTags = span.copy(metricTags =
     TagSet.from(
       Map(
         "string" -> "value",
@@ -104,7 +104,7 @@ trait TestData {
       "false" -> "false",
       "number" -> randomNumber.toString,
       "component" -> "custom.component",
-      "env" -> "staging",
+      "env" -> "staging"
     )
   )
 
@@ -115,7 +115,7 @@ trait TestData {
   val jsonWithMarks = json ++ Json.obj(
     "meta" -> Json.obj(
       "from" -> JsString(from.getEpochNano.toString),
-        "env" -> JsString("staging")
+      "env" -> JsString("staging")
     )
   )
 
@@ -144,8 +144,8 @@ trait TestData {
     "span with meta and marks" -> (Seq(spanWithTagsAndMarks), Json.arr(Json.arr(jsonWithTagsAndMarks))),
     "span with error" -> (Seq(spanWithError), Json.arr(Json.arr(jsonWithError))),
 
-    "multiple spans with same trace" -> (Seq(span, spanWithTags), Json.arr(Json.arr(json, jsonWithTags))),
-    // "multiple spans with two traces" -> (Seq(span, spanWithTags, otherTraceSpan, span), Json.arr(Json.arr(json, jsonWithTags, json), Json.arr(otherTraceJson)))
+    "multiple spans with same trace" -> (Seq(span, spanWithTags), Json.arr(Json.arr(json, jsonWithTags)))
+  // "multiple spans with two traces" -> (Seq(span, spanWithTags, otherTraceSpan, span), Json.arr(Json.arr(json, jsonWithTags, json), Json.arr(otherTraceJson)))
   )
 }
 
@@ -165,7 +165,7 @@ class DatadogSpanReporterSpec extends AbstractHttpReporter with Matchers with Re
 
         val baseUrl = mockResponse("/test", new MockResponse().setStatus("HTTP/1.1 200 OK").setBody("OK"))
 
-        applyConfig("kamon.datadog.trace.http.api-url = \"" + baseUrl + "\"")
+        applyConfig("kamon.datadog.trace.api-url = \"" + baseUrl + "\"")
         reporter.reconfigure(Kamon.config())
         reporter.reportSpans(spans)
         val request = server.takeRequest()
@@ -186,7 +186,7 @@ class DatadogSpanReporterSpec extends AbstractHttpReporter with Matchers with Re
 
     s"ignore error responses" in {
       val baseUrl = mockResponse("/test", new MockResponse().setStatus("HTTP/1.1 500 Internal Server Error"))
-      applyConfig("kamon.datadog.trace.http.api-url = \"" + baseUrl + "\"")
+      applyConfig("kamon.datadog.trace.api-url = \"" + baseUrl + "\"")
       reporter.reconfigure(Kamon.config())
       reporter.reportSpans(firstSpan)
       server.takeRequest()