feat: Add labels support to LongGaugeMetric.

Author: bgrozev

jicoco-metrics/src/main/kotlin/org/jitsi/metrics/LongGaugeMetric.kt

@@ -32,52 +32,109 @@ class LongGaugeMetric @JvmOverloads constructor(
     /** the namespace (prefix) of this metric */
     namespace: String,
     /** an optional initial value for this metric */
-    internal val initialValue: Long = 0L
+    internal val initialValue: Long = 0L,
+    /** Label names for this metric. If non-empty, the initial value must be 0 and all get/update calls MUST
+     * specify values for the labels. Calls to simply get() or set() will fail with an exception. */
+    val labelNames: List<String> = emptyList()
 ) : Metric<Long>() {
-    private val gauge = Gauge.build(name, help).namespace(namespace).create().apply { set(initialValue.toDouble()) }
+    private val gauge = run {
+        val builder = Gauge.build(name, help).namespace(namespace)
+        if (labelNames.isNotEmpty()) {
+            builder.labelNames(*labelNames.toTypedArray())
+            if (initialValue != 0L) {
+                throw IllegalArgumentException("Cannot set an initial value for a labeled gauge")
+            }
+        }
+        builder.create().apply {
+            if (initialValue != 0L) {
+                set(initialValue.toDouble())
+            }
+        }
+    }
 
+    /** When we have labels [get()] throws an exception and the JSON format is not supported. */
+    override val supportsJson: Boolean = labelNames.isEmpty()
     override fun get() = gauge.get().toLong()
+    fun get(labels: List<String>) = gauge.labels(*labels.toTypedArray()).get().toLong()
 
-    override fun reset() = set(initialValue)
+    override fun reset() = synchronized(gauge) {
+        gauge.clear()
+        if (initialValue != 0L) {
+            gauge.inc(initialValue.toDouble())
+        }
+    }
 
     override fun register(registry: CollectorRegistry) = this.also { registry.register(gauge) }
 
     /**
      * Atomically sets the gauge to the given value.
      */
-    fun set(newValue: Long): Unit = synchronized(gauge) { gauge.set(newValue.toDouble()) }
+    fun set(newValue: Long, labels: List<String> = emptyList()): Unit = synchronized(gauge) {
+        if (labels.isEmpty()) {
+            gauge.set(newValue.toDouble())
+        } else {
+            gauge.labels(*labels.toTypedArray()).set(newValue.toDouble())
+        }
+    }
 
     /**
      * Atomically increments the value of this gauge by one.
      */
-    fun inc() = synchronized(gauge) { gauge.inc() }
+    fun inc(labels: List<String> = emptyList()) = synchronized(gauge) {
+        if (labels.isEmpty()) {
+            gauge.inc()
+        } else {
+            gauge.labels(*labels.toTypedArray()).inc()
+        }
+    }
 
     /**
      * Atomically decrements the value of this gauge by one.
      */
-    fun dec() = synchronized(gauge) { gauge.dec() }
+    fun dec(labels: List<String> = emptyList()) = synchronized(gauge) {
+        if (labels.isEmpty()) {
+            gauge.dec()
+        } else {
+            gauge.labels(*labels.toTypedArray()).dec()
+        }
+    }
 
     /**
      * Atomically adds the given value to this gauge, returning the updated value.
      *
      * @return the updated value
      */
-    fun addAndGet(delta: Long): Long = synchronized(gauge) {
-        gauge.inc(delta.toDouble())
-        return gauge.get().toLong()
+    fun addAndGet(delta: Long, labels: List<String> = emptyList()): Long = synchronized(gauge) {
+        return if (labels.isEmpty()) {
+            gauge.inc(delta.toDouble())
+            gauge.get().toLong()
+        } else {
+            with(gauge.labels(*labels.toTypedArray())) {
+                inc(delta.toDouble())
+                get().toLong()
+            }
+        }
     }
 
     /**
      * Atomically increments the value of this gauge by one, returning the updated value.
      *
      * @return the updated value
      */
-    fun incAndGet() = addAndGet(1)
+    fun incAndGet(labels: List<String> = emptyList()) = addAndGet(1, labels)
 
     /**
      * Atomically decrements the value of this gauge by one, returning the updated value.
      *
      * @return the updated value
      */
-    fun decAndGet() = addAndGet(-1)
+    fun decAndGet(labels: List<String> = emptyList()) = addAndGet(-1, labels)
+
+    /** Remove the child with the given labels (the metric with those labels will stop being emitted) */
+    fun remove(labels: List<String> = emptyList()) = synchronized(gauge) {
+        if (labels.isNotEmpty()) {
+            gauge.remove(*labels.toTypedArray())
+        }
+    }
+    internal fun collect() = gauge.collect()
 }

jicoco-metrics/src/main/kotlin/org/jitsi/metrics/MetricsContainer.kt

@@ -178,15 +178,20 @@ open class MetricsContainer @JvmOverloads constructor(
         /** the description of the metric */
         help: String,
         /** the optional initial value of the metric */
-        initialValue: Long = 0
+        initialValue: Long = 0,
+        /** Label names for this metric. If non-empty, the initial value must be 0 and all get/update calls MUST
+         * specify values for the labels. Calls to simply get() or set() will fail with an exception. */
+        labelNames: List<String> = emptyList()
     ): LongGaugeMetric {
         if (metrics.containsKey(name)) {
             if (checkForNameConflicts) {
                 throw RuntimeException("Could not register metric '$name'. A metric with that name already exists.")
             }
             return metrics[name] as LongGaugeMetric
         }
-        return LongGaugeMetric(name, help, namespace, initialValue).apply { metrics[name] = register(registry) }
+        return LongGaugeMetric(name, help, namespace, initialValue, labelNames).apply {
+            metrics[name] = register(registry)
+        }
     }
 
     /**

jicoco-metrics/src/test/kotlin/org/jitsi/metrics/MetricTest.kt

@@ -241,6 +241,44 @@ class MetricTest : ShouldSpec() {
                     should("return the initial value") { get() shouldBe initialValue }
                 }
             }
+            context("With labels") {
+                with(LongGaugeMetric("testLongGauge", "Help", namespace, labelNames = listOf("l1", "l2"))) {
+                    val labels = listOf("A", "A")
+                    val labels2 = listOf("A", "B")
+                    val labels3 = listOf("B", "B")
+
+                    get(labels) shouldBe 0
+                    get(labels2) shouldBe 0
+                    get(labels3) shouldBe 0
+
+                    addAndGet(3, labels) shouldBe 3
+                    get(labels) shouldBe 3
+                    get(labels2) shouldBe 0
+                    get(labels3) shouldBe 0
+
+                    incAndGet(labels2)
+                    get(labels) shouldBe 3
+                    get(labels2) shouldBe 1
+                    get(labels3) shouldBe 0
+
+                    incAndGet(labels3) shouldBe 1
+
+                    addAndGet(2, labels)
+                    get(labels) shouldBe 5
+                    get(labels2) shouldBe 1
+                    get(labels3) shouldBe 1
+
+                    collect()[0].samples.size shouldBe 3
+                    remove(labels2)
+                    // Down to two sets of labels
+                    collect()[0].samples.size shouldBe 2
+                    get(labels) shouldBe 5
+                    get(labels2) shouldBe 0
+                    get(labels3) shouldBe 1
+                    // Even a get() will summon a child
+                    collect()[0].samples.size shouldBe 3
+                }
+            }
         }
         context("Creating an InfoMetric") {
             context("with a value different from its name") {