sdk-metrics: add ExemplarFilter and TraceContextLookup

sdk/metrics/src/main/scala/org/typelevel/otel4s/sdk/metrics/data/ExemplarData.scala

@@ -73,10 +73,14 @@ object ExemplarData {
   sealed trait DoubleExemplar extends ExemplarData { type Value = Double }
 
   /** The trace information.
+    *
+    * [[TraceContext]] is a minimal version of SpanContext. That way,
+    * `sdk-metrics` does not need to depend on the `core-trace`.
     */
   sealed trait TraceContext {
     def traceId: ByteVector
     def spanId: ByteVector
+    def isSampled: Boolean
 
     override final def hashCode(): Int =
       Hash[TraceContext].hash(this)
@@ -95,22 +99,27 @@ object ExemplarData {
 
     /** Creates a [[TraceContext]] with the given `traceId` and `spanId`.
       */
-    def apply(traceId: ByteVector, spanId: ByteVector): TraceContext =
-      Impl(traceId, spanId)
+    def apply(
+        traceId: ByteVector,
+        spanId: ByteVector,
+        sampled: Boolean
+    ): TraceContext =
+      Impl(traceId, spanId, sampled)
 
     implicit val traceContextShow: Show[TraceContext] =
       Show.show { c =>
-        s"TraceContext{traceId=${c.traceId.toHex}, spanId=${c.spanId.toHex}}"
+        s"TraceContext{traceId=${c.traceId.toHex}, spanId=${c.spanId.toHex}, isSampled=${c.isSampled}}"
       }
 
     implicit val traceContextHash: Hash[TraceContext] = {
       implicit val byteVectorHash: Hash[ByteVector] = Hash.fromUniversalHashCode
-      Hash.by(c => (c.traceId, c.spanId))
+      Hash.by(c => (c.traceId, c.spanId, c.isSampled))
     }
 
     private final case class Impl(
         traceId: ByteVector,
-        spanId: ByteVector
+        spanId: ByteVector,
+        isSampled: Boolean
     ) extends TraceContext
   }
 

sdk/metrics/src/main/scala/org/typelevel/otel4s/sdk/metrics/exemplar/ExemplarFilter.scala

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2024 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.sdk.metrics.exemplar
+
+import org.typelevel.otel4s.Attributes
+import org.typelevel.otel4s.metrics.MeasurementValue
+import org.typelevel.otel4s.sdk.context.Context
+
+/** Exemplar filters are used to pre-filter measurements before attempting to
+  * store them in a reservoir.
+  *
+  * @see
+  *   [[https://opentelemetry.io/docs/specs/otel/metrics/sdk/#exemplarfilter]]
+  */
+sealed trait ExemplarFilter {
+
+  /** Returns whether or not a reservoir should attempt to sample a measurement.
+    */
+  def shouldSample[A: MeasurementValue](
+      value: A,
+      attributes: Attributes,
+      context: Context
+  ): Boolean
+}
+
+object ExemplarFilter {
+  private val AlwaysOn = new Const(decision = true)
+  private val AlwaysOff = new Const(decision = false)
+
+  /** A filter which makes all measurements eligible for being an exemplar.
+    */
+  def alwaysOn: ExemplarFilter = AlwaysOn
+
+  /** A filter which makes no measurements eligible for being an exemplar.
+    */
+  def alwaysOff: ExemplarFilter = AlwaysOff
+
+  /** A filter that only accepts measurements where there is a span in a context
+    * that is being sampled.
+    */
+  def traceBased(lookup: TraceContextLookup): ExemplarFilter =
+    new TraceBased(lookup)
+
+  private final class Const(decision: Boolean) extends ExemplarFilter {
+    def shouldSample[A: MeasurementValue](
+        value: A,
+        attributes: Attributes,
+        context: Context
+    ): Boolean =
+      decision
+  }
+
+  private final class TraceBased(
+      lookup: TraceContextLookup
+  ) extends ExemplarFilter {
+    def shouldSample[A: MeasurementValue](
+        value: A,
+        attributes: Attributes,
+        context: Context
+    ): Boolean =
+      lookup.get(context).exists(_.isSampled)
+  }
+}

sdk/metrics/src/main/scala/org/typelevel/otel4s/sdk/metrics/exemplar/TraceContextLookup.scala

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2024 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.sdk.metrics.exemplar
+
+import org.typelevel.otel4s.sdk.context.Context
+import org.typelevel.otel4s.sdk.metrics.data.ExemplarData.TraceContext
+
+/** Provides a way to extract [[TraceContext]] from the [[Context]].
+  */
+trait TraceContextLookup {
+  def get(context: Context): Option[TraceContext]
+}
+
+object TraceContextLookup {
+  def noop: TraceContextLookup = Noop
+
+  private object Noop extends TraceContextLookup {
+    def get(context: Context): Option[TraceContext] = None
+  }
+}

sdk/metrics/src/test/scala/org/typelevel/otel4s/sdk/metrics/exemplar/ExemplarFilterSuite.scala

@@ -0,0 +1,94 @@
+/*
+ * Copyright 2024 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.sdk.metrics.exemplar
+
+import cats.effect.SyncIO
+import munit.ScalaCheckSuite
+import org.scalacheck.Gen
+import org.scalacheck.Prop
+import org.typelevel.otel4s.sdk.context.Context
+import org.typelevel.otel4s.sdk.metrics.data.ExemplarData
+import org.typelevel.otel4s.sdk.metrics.scalacheck.Gens
+
+class ExemplarFilterSuite extends ScalaCheckSuite {
+
+  private val valueGen: Gen[Either[Long, Double]] =
+    Gen.either(Gen.long, Gen.double)
+
+  private val traceContextKey = Context.Key
+    .unique[SyncIO, ExemplarData.TraceContext]("trace-context")
+    .unsafeRunSync()
+
+  test("alwaysOn - allow all values") {
+    val filter = ExemplarFilter.alwaysOn
+
+    Prop.forAll(valueGen, Gens.attributes) {
+      case (Left(value), attributes) =>
+        assert(filter.shouldSample(value, attributes, Context.root))
+
+      case (Right(value), attributes) =>
+        assert(filter.shouldSample(value, attributes, Context.root))
+    }
+  }
+
+  test("alwaysOff - forbid all values") {
+    val filter = ExemplarFilter.alwaysOff
+
+    Prop.forAll(valueGen, Gens.attributes) {
+      case (Left(value), attributes) =>
+        assert(!filter.shouldSample(value, attributes, Context.root))
+
+      case (Right(value), attributes) =>
+        assert(!filter.shouldSample(value, attributes, Context.root))
+    }
+  }
+
+  test("traceBased - forbid all values when TraceContextLookup is noop") {
+    val filter = ExemplarFilter.traceBased(TraceContextLookup.noop)
+
+    Prop.forAll(valueGen, Gens.attributes) {
+      case (Left(value), attributes) =>
+        assert(!filter.shouldSample(value, attributes, Context.root))
+
+      case (Right(value), attributes) =>
+        assert(!filter.shouldSample(value, attributes, Context.root))
+    }
+  }
+
+  test("traceBased - decide according to the tracing context") {
+    val filter = ExemplarFilter.traceBased(_.get(traceContextKey))
+
+    Prop.forAll(valueGen, Gens.attributes, Gens.traceContext) {
+      case (Left(value), attributes, traceContext) =>
+        val ctx = Context.root.updated(traceContextKey, traceContext)
+
+        assertEquals(
+          filter.shouldSample(value, attributes, ctx),
+          traceContext.isSampled
+        )
+
+      case (Right(value), attributes, traceContext) =>
+        val ctx = Context.root.updated(traceContextKey, traceContext)
+
+        assertEquals(
+          filter.shouldSample(value, attributes, ctx),
+          traceContext.isSampled
+        )
+    }
+  }
+
+}

sdk/metrics/src/test/scala/org/typelevel/otel4s/sdk/metrics/scalacheck/Gens.scala

@@ -119,9 +119,11 @@ trait Gens extends org.typelevel.otel4s.sdk.scalacheck.Gens {
     for {
       traceId <- Gen.stringOfN(16, Gen.hexChar)
       spanId <- Gen.stringOfN(8, Gen.hexChar)
+      sampled <- Gen.oneOf(true, false)
     } yield ExemplarData.TraceContext(
       ByteVector.fromValidHex(traceId),
-      ByteVector.fromValidHex(spanId)
+      ByteVector.fromValidHex(spanId),
+      sampled
     )
 
   val longExemplarData: Gen[ExemplarData.LongExemplar] =