! all: refactor the core metric recording instruments and accomodate UserMetrics

This PR is including several changes to the kamon-core, most notably:
  - Formalize the interface for Histograms, Counters and MinMaxCounters. Making sure
    that the interfaces are as clean as possible.
  - Move away from the all Vector[Measurement] based Histogram snapshot to a new approach
    in which we use a single long to store both the index in the counts array and the
    frequency on that bucket. The leftmost 2 bytes of each long are used for storing the
    counts array index and the remaining 6 bytes are used for the actual count, and
    everything is put into a simple long array. This way only the buckets that actually
    have values will be included in the snapshot with the smallest possible memory
    footprint.
  - Introduce Gauges.
  - Reorganize the instrumentation for Akka and Scala and rewrite most of the tests
    of this components to avoid going through the subscription protocol to test.
  - Introduce trace tests and fixes on various tests.
  - Necessary changes on new relic, datadog and statsd modules to compile with the new
    codebase.

Pending:
  - Finish the upgrade of the new relic to the current model.
  - Introduce proper limit checks for histograms to ensure that we never pass the 2/6 bytes
    limits.
  - More testing, more testing, more testing.
  - Create the KamonStandalone module.

1 files changed, 95 insertions, 0 deletions

diff --git a/kamon-core/src/test/scala/kamon/trace/TraceContextManipulationSpec.scala b/kamon-core/src/test/scala/kamon/trace/TraceContextManipulationSpec.scala
new file mode 100644
index 00000000..4d0049f1
--- /dev/null
+++ b/kamon-core/src/test/scala/kamon/trace/TraceContextManipulationSpec.scala
@@ -0,0 +1,95 @@
+package kamon.trace
+
+import akka.actor.ActorSystem
+import akka.testkit.{ ImplicitSender, TestKitBase }
+import com.typesafe.config.ConfigFactory
+import kamon.trace.TraceContext.SegmentIdentity
+import org.scalatest.{ Matchers, WordSpecLike }
+
+class TraceContextManipulationSpec extends TestKitBase with WordSpecLike with Matchers with ImplicitSender {
+  implicit lazy val system: ActorSystem = ActorSystem("trace-metrics-spec", ConfigFactory.parseString(
+    """
+      |kamon.metrics {
+      |  tick-interval = 1 hour
+      |  filters = [
+      |    {
+      |      trace {
+      |        includes = [ "*" ]
+      |        excludes = [ "non-tracked-trace"]
+      |      }
+      |    }
+      |  ]
+      |  precision {
+      |    default-histogram-precision {
+      |      highest-trackable-value = 3600000000000
+      |      significant-value-digits = 2
+      |    }
+      |
+      |    default-min-max-counter-precision {
+      |      refresh-interval = 1 second
+      |      highest-trackable-value = 999999999
+      |      significant-value-digits = 2
+      |    }
+      |  }
+      |}
+    """.stripMargin))
+
+  "the TraceRecorder api" should {
+    "allow starting a trace within a specified block of code, and only within that block of code" in {
+      val createdContext = TraceRecorder.withNewTraceContext("start-context") {
+        TraceRecorder.currentContext should not be empty
+        TraceRecorder.currentContext.get
+      }
+
+      TraceRecorder.currentContext shouldBe empty
+      createdContext.name shouldBe ("start-context")
+    }
+
+    "allow starting a trace within a specified block of code, providing a trace-token and only within that block of code" in {
+      val createdContext = TraceRecorder.withNewTraceContext("start-context-with-token", Some("token-1")) {
+        TraceRecorder.currentContext should not be empty
+        TraceRecorder.currentContext.get
+      }
+
+      TraceRecorder.currentContext shouldBe empty
+      createdContext.name shouldBe ("start-context-with-token")
+      createdContext.token should be("token-1")
+    }
+
+    "allow providing a TraceContext and make it available within a block of code" in {
+      val createdContext = TraceRecorder.withNewTraceContext("manually-provided-trace-context") { TraceRecorder.currentContext }
+
+      TraceRecorder.currentContext shouldBe empty
+      TraceRecorder.withTraceContext(createdContext) {
+        TraceRecorder.currentContext should be(createdContext)
+      }
+
+      TraceRecorder.currentContext shouldBe empty
+    }
+
+    "allow renaming a trace" in {
+      val createdContext = TraceRecorder.withNewTraceContext("trace-before-rename") {
+        TraceRecorder.rename("renamed-trace")
+        TraceRecorder.currentContext.get
+      }
+
+      TraceRecorder.currentContext shouldBe empty
+      createdContext.name shouldBe ("renamed-trace")
+    }
+
+    "allow creating a segment within a trace" in {
+      val createdContext = TraceRecorder.withNewTraceContext("trace-with-segments") {
+        val segmentHandle = TraceRecorder.startSegment(TraceManipulationTestSegment("segment-1"))
+
+        TraceRecorder.currentContext.get
+      }
+
+      TraceRecorder.currentContext shouldBe empty
+      createdContext.name shouldBe ("trace-with-segments")
+
+    }
+  }
+
+  case class TraceManipulationTestSegment(name: String) extends SegmentIdentity
+
+}