metrics: support synchronous gauge

build.sbt

@@ -1,4 +1,4 @@
-ThisBuild / tlBaseVersion := "0.7"
+ThisBuild / tlBaseVersion := "0.8"
 
 ThisBuild / organization := "org.typelevel"
 ThisBuild / organizationName := "Typelevel"

core/metrics/src/main/scala-2/org/typelevel/otel4s/metrics/GaugeMacro.scala

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2022 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.typelevel.otel4s
+package metrics
+
+import scala.collection.immutable
+
+private[otel4s] trait GaugeMacro[F[_], A] {
+  def backend: Gauge.Backend[F, A]
+
+  /** Records a value with a set of attributes.
+    *
+    * @param value
+    *   the value to record
+    *
+    * @param attributes
+    *   the set of attributes to associate with the value
+    */
+  def record(value: A, attributes: Attribute[_]*): F[Unit] =
+    macro GaugeMacro.record[A]
+
+  /** Records a value with a set of attributes.
+    *
+    * @param value
+    *   the value to record
+    *
+    * @param attributes
+    *   the set of attributes to associate with the value
+    */
+  def record(value: A, attributes: immutable.Iterable[Attribute[_]]): F[Unit] =
+    macro GaugeMacro.recordColl[A]
+
+}
+
+object GaugeMacro {
+  import scala.reflect.macros.blackbox
+
+  def record[A](c: blackbox.Context)(
+      value: c.Expr[A],
+      attributes: c.Expr[Attribute[_]]*
+  ): c.universe.Tree = {
+    import c.universe._
+    recordColl(c)(value, c.Expr(q"_root_.scala.Seq(..$attributes)"))
+  }
+
+  def recordColl[A](c: blackbox.Context)(
+      value: c.Expr[A],
+      attributes: c.Expr[immutable.Iterable[Attribute[_]]]
+  ): c.universe.Tree = {
+    import c.universe._
+    val backend = q"${c.prefix}.backend"
+    val meta = q"$backend.meta"
+
+    q"if ($meta.isEnabled) $backend.record($value, $attributes) else $meta.unit"
+  }
+
+}

core/metrics/src/main/scala-3/org/typelevel/otel4s/metrics/GaugeMacro.scala

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2022 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.typelevel.otel4s
+package metrics
+
+import scala.collection.immutable
+import scala.quoted.*
+
+private[otel4s] trait GaugeMacro[F[_], A] {
+  def backend: Gauge.Backend[F, A]
+
+  /** Records a value with a set of attributes.
+    *
+    * @param value
+    *   the value to record
+    *
+    * @param attributes
+    *   the set of attributes to associate with the value
+    */
+  inline def record(
+      inline value: A,
+      inline attributes: Attribute[_]*
+  ): F[Unit] =
+    ${ GaugeMacro.record('backend, 'value, 'attributes) }
+
+  /** Records a value with a set of attributes.
+    *
+    * @param value
+    *   the value to record
+    *
+    * @param attributes
+    *   the set of attributes to associate with the value
+    */
+  inline def record(
+      inline value: A,
+      inline attributes: immutable.Iterable[Attribute[_]]
+  ): F[Unit] =
+    ${ GaugeMacro.record('backend, 'value, 'attributes) }
+
+}
+
+object GaugeMacro {
+
+  def record[F[_], A](
+      backend: Expr[Gauge.Backend[F, A]],
+      value: Expr[A],
+      attributes: Expr[immutable.Iterable[Attribute[_]]]
+  )(using Quotes, Type[F], Type[A]) =
+    '{
+      if ($backend.meta.isEnabled) $backend.record($value, $attributes)
+      else $backend.meta.unit
+    }
+
+}

core/metrics/src/main/scala/org/typelevel/otel4s/metrics/Gauge.scala

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2022 Typelevel
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.typelevel.otel4s
+package metrics
+
+import cats.Applicative
+import org.typelevel.otel4s.meta.InstrumentMeta
+
+import scala.collection.immutable
+
+/** A `Gauge` instrument that records non-additive values of type `A`.
+  *
+  * @see
+  *   See [[UpDownCounter]] to record additive values
+  *
+  * @see
+  *   [[https://opentelemetry.io/docs/specs/otel/metrics/api/#gauge]]
+  *
+  * @tparam F
+  *   the higher-kinded type of a polymorphic effect
+  *
+  * @tparam A
+  *   the type of the values to record. The type must have an instance of
+  *   [[MeasurementValue]]. [[scala.Long]] and [[scala.Double]] are supported
+  *   out of the box.
+  */
+trait Gauge[F[_], A] extends GaugeMacro[F, A]
+
+object Gauge {
+
+  /** A builder of [[Gauge]].
+    *
+    * @tparam F
+    *   the higher-kinded type of a polymorphic effect
+    *
+    * @tparam A
+    *   the type of the values to record. The type must have an instance of
+    *   [[MeasurementValue]]. [[scala.Long]] and [[scala.Double]] are supported
+    *   out of the box.
+    */
+  trait Builder[F[_], A] {
+
+    /** Sets the unit of measure for this counter.
+      *
+      * @see
+      *   [[https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-unit Instrument Unit]]
+      *
+      * @param unit
+      *   the measurement unit. Must be 63 or fewer ASCII characters.
+      */
+    def withUnit(unit: String): Builder[F, A]
+
+    /** Sets the description for this gauge.
+      *
+      * @see
+      *   [[https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-description Instrument Description]]
+      *
+      * @param description
+      *   the description
+      */
+    def withDescription(description: String): Builder[F, A]
+
+    /** Creates a [[Gauge]] with the given `unit` and `description` (if any).
+      */
+    def create: F[Gauge[F, A]]
+  }
+
+  trait Backend[F[_], A] {
+    def meta: InstrumentMeta[F]
+
+    /** Records a value with a set of attributes.
+      *
+      * @param value
+      *   the value to record
+      *
+      * @param attributes
+      *   the set of attributes to associate with the value
+      */
+    def record(value: A, attributes: immutable.Iterable[Attribute[_]]): F[Unit]
+
+  }
+
+  def noop[F[_], A](implicit F: Applicative[F]): Gauge[F, A] =
+    new Gauge[F, A] {
+      val backend: Backend[F, A] =
+        new Backend[F, A] {
+          val meta: InstrumentMeta[F] = InstrumentMeta.disabled
+          def record(
+              value: A,
+              attributes: immutable.Iterable[Attribute[_]]
+          ): F[Unit] = meta.unit
+        }
+    }
+
+  private[otel4s] def fromBackend[F[_], A](b: Backend[F, A]): Gauge[F, A] =
+    new Gauge[F, A] {
+      def backend: Backend[F, A] = b
+    }
+
+}

core/metrics/src/main/scala/org/typelevel/otel4s/metrics/Meter.scala

@@ -135,6 +135,37 @@ trait Meter[F[_]] {
       name: String
   ): UpDownCounter.Builder[F, A]
 
+  /** Creates a builder of [[Gauge]] instrument that records values of type `A`.
+    *
+    * The [[Gauge]] records non-additive values.
+    *
+    * @note
+    *   the `A` type must be provided explicitly, for example
+    *   `meter.gauge[Long]` or `meter.gauge[Double]`
+    *
+    * @example
+    *   {{{
+    * val meter: Meter[F] = ???
+    *
+    * val doubleGauge: F[Gauge[F, Double]] =
+    *   meter.gauge[Double]("double-gauge").create
+    *
+    * val longGauge: F[Gauge[F, Long]] =
+    *   meter.gauge[Long]("long-gauge").create
+    *   }}}
+    *
+    * @see
+    *   See [[upDownCounter]] to record additive values
+    *
+    * @param name
+    *   the name of the instrument
+    *
+    * @tparam A
+    *   the type of the measurement. [[scala.Long]] and [[scala.Double]] are
+    *   supported out of the box
+    */
+  def gauge[A: MeasurementValue](name: String): Gauge.Builder[F, A]
+
   /** Creates a builder of [[ObservableGauge]] instrument that collects values
     * of type `A` from the given callback.
     *
@@ -326,6 +357,13 @@ object Meter {
           def create: F[UpDownCounter[F, A]] = F.pure(UpDownCounter.noop)
         }
 
+      def gauge[A: MeasurementValue](name: String): Gauge.Builder[F, A] =
+        new Gauge.Builder[F, A] {
+          def withUnit(unit: String): Gauge.Builder[F, A] = this
+          def withDescription(description: String): Gauge.Builder[F, A] = this
+          def create: F[Gauge[F, A]] = F.pure(Gauge.noop)
+        }
+
       def observableGauge[A: MeasurementValue](
           name: String
       ): ObservableGauge.Builder[F, A] =

core/metrics/src/test/scala/org/typelevel/otel4s/metrics/BaseMeterSuite.scala

@@ -65,6 +65,17 @@ abstract class BaseMeterSuite extends CatsEffectSuite {
     } yield assertEquals(metrics, List(expected))
   }
 
+  sdkTest("Gauge - record values") { sdk =>
+    val expected = MetricData.gauge("gauge", 1L, Some(1L))
+
+    for {
+      meter <- sdk.provider.get("meter")
+      gauge <- meter.gauge[Long]("gauge").create
+      _ <- gauge.record(1L)
+      metrics <- sdk.collectMetrics
+    } yield assertEquals(metrics, List(expected))
+  }
+
   sdkTest("UpDownCounter - record values") { sdk =>
     val expected = MetricData.sum("counter", monotonic = false, 3L, Some(3L))
 
@@ -376,7 +387,11 @@ object BaseMeterSuite {
         )
       )
 
-    def gauge(name: String, value: Long): MetricData =
+    def gauge(
+        name: String,
+        value: Long,
+        exemplarValue: Option[Long] = None
+    ): MetricData =
       MetricData(
         name,
         None,
@@ -388,7 +403,15 @@ object BaseMeterSuite {
               Duration.Zero,
               Attributes.empty,
               Left(value),
-              Vector.empty
+              exemplarValue.toVector.map { exemplar =>
+                Exemplar(
+                  Attributes.empty,
+                  Duration.Zero,
+                  Some(TraceId),
+                  Some(SpanId),
+                  Left(exemplar)
+                )
+              }
             )
           )
         )