utility class to keep track of instrument groups

Author: ivantopo

kamon-core-tests/src/test/scala/kamon/metric/InstrumentGroupSpec.scala

@@ -0,0 +1,63 @@
+package kamon.metric
+
+import kamon.Kamon
+import kamon.tag.TagSet
+import kamon.testkit.MetricInspection
+import org.scalatest.{Matchers, WordSpec}
+
+class InstrumentGroupSpec extends WordSpec with MetricInspection.Syntax with Matchers {
+
+  "an Instrument Group" should {
+    "register instruments with common tags and remove them when cleaning up" in {
+      val group = new CommonTagsOnly(TagSet.of("type", "common"))
+
+      Counter.tagValues("type") should contain only("common")
+      Gauge.tagValues("type") should contain only("common")
+      Histogram.tagValues("type") should contain only("common")
+      RangeSampler.tagValues("type") should contain only("common")
+
+      group.remove()
+
+      Counter.tagValues("type") shouldBe empty
+      Gauge.tagValues("type") shouldBe empty
+      Histogram.tagValues("type") shouldBe empty
+      RangeSampler.tagValues("type") shouldBe empty
+    }
+
+    "override common tags with tags supplied to the register method" in {
+      val group = new MixedTags(TagSet.of("type", "basic"))
+
+      Counter.tagValues("type") should contain only("basic")
+      Gauge.tagValues("type") should contain only("simple")
+      Histogram.tagValues("type") should contain only("42")
+      RangeSampler.tagValues("type") should contain only("true")
+
+      group.remove()
+
+      Counter.tagValues("type") shouldBe empty
+      Gauge.tagValues("type") shouldBe empty
+      Histogram.tagValues("type") shouldBe empty
+      RangeSampler.tagValues("type") shouldBe empty
+    }
+  }
+
+
+  val Counter = Kamon.counter("metric.group.counter")
+  val Gauge = Kamon.gauge("metric.group.gauge")
+  val Histogram = Kamon.histogram("metric.group.histogram")
+  val RangeSampler = Kamon.rangeSampler("metric.group.range-sampler")
+
+  class CommonTagsOnly(tags: TagSet) extends InstrumentGroup(tags) {
+    val counter = register(Counter)
+    val gauge = register(Gauge)
+    val histogram = register(Histogram)
+    val rangeSampler = register(RangeSampler)
+  }
+
+  class MixedTags(tags: TagSet) extends InstrumentGroup(tags) {
+    val counter = register(Counter)
+    val gauge = register(Gauge, "type", "simple")
+    val histogram = register(Histogram, "type", 42)
+    val rangeSampler = register(RangeSampler, "type", true)
+  }
+}

kamon-core/src/main/scala/kamon/metric/Instrument.scala

@@ -8,7 +8,7 @@ import kamon.tag.TagSet
 /**
   * Base user-facing API for all metric instruments in Kamon.
   */
-trait Instrument[Inst, Sett <: Metric.Settings] extends Tagging[Inst] {
+trait Instrument[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings] extends Tagging[Inst] {
 
   /**
     * Returns the metric to which this instrument belongs.

kamon-core/src/main/scala/kamon/metric/InstrumentGroup.scala

@@ -0,0 +1,65 @@
+package kamon
+package metric
+
+import kamon.tag.TagSet
+
+/**
+  * Utility class for handling groups of instruments that should be created and removed together. This becomes specially
+  * handy when using several instruments to track different aspects of the same component. For example, when tracking
+  * metrics on a thread pool you will want to request several instruments to track different aspects: the pool size, the
+  * number of submitted tasks, the queue size and so on, and all of those instruments should share common tags that are
+  * specific to the instrumented thread pool; additionally, once said thread pool is shutdown, all of those instruments
+  * should be removed together. This class makes it simpler to keep track of all of those related instruments and remove
+  * them together when necessary.
+  */
+abstract class InstrumentGroup(val commonTags: TagSet) {
+  private var _groupInstruments = List.empty[Instrument[_, _]]
+
+  /**
+    * Registers and returns an instrument of the provided metric with the common tags.
+    */
+  def register[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings](metric: Metric[Inst, Sett]): Inst =
+    registerInstrument(metric, commonTags)
+
+  /**
+    * Registers and returns an instrument of the provided metric with the common tags and the additionally provided
+    * key/value pair.
+    */
+  def register[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings](metric: Metric[Inst, Sett], key: String, value: String): Inst =
+    registerInstrument(metric, commonTags.withTag(key, value))
+
+  /**
+    * Registers and returns an instrument of the provided metric with the common tags and the additionally provided
+    * key/value pair.
+    */
+  def register[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings](metric: Metric[Inst, Sett], key: String, value: Long): Inst =
+    registerInstrument(metric, commonTags.withTag(key, value))
+
+  /**
+    * Registers and returns an instrument of the provided metric with the common tags and the additionally provided
+    * key/value pair.
+    */
+  def register[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings](metric: Metric[Inst, Sett], key: String, value: Boolean): Inst =
+    registerInstrument(metric, commonTags.withTag(key, value))
+
+  /**
+    * Registers and returns an instrument of the provided metric with the common tags and the additionally provided tags.
+    */
+  def register[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings](metric: Metric[Inst, Sett], extraTags: TagSet): Inst =
+    registerInstrument(metric, commonTags.withTags(extraTags))
+
+
+  private def registerInstrument[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings](metric: Metric[Inst, Sett],
+      tags: TagSet): Inst = synchronized {
+    val instrument = metric.withTags(tags)
+    _groupInstruments = instrument :: _groupInstruments
+    instrument
+  }
+
+  /**
+    * Removes all instruments that were registered by this group.
+    */
+  def remove(): Unit = synchronized {
+    _groupInstruments foreach(_.remove())
+  }
+}

kamon-core/src/main/scala/kamon/metric/Metric.scala

@@ -22,7 +22,7 @@ import scala.collection.mutable
   * combination of tags used to create them.
   *
   */
-trait Metric[Inst, Sett <: Metric.Settings] extends Tagging[Inst] {
+trait Metric[Inst <: Instrument[Inst, Sett], Sett <: Metric.Settings] extends Tagging[Inst] {
 
   /**
     * A unique identifier for this metric. Metric names typically will be namespaced, meaning that their name has a