Add exemplars feature

opentelemetry-api/src/opentelemetry/metrics/_internal/instrument.py

@@ -33,6 +33,7 @@
 
 # pylint: disable=unused-import; needed for typing and sphinx
 from opentelemetry import metrics
+from opentelemetry.context import Context
 from opentelemetry.metrics._internal.observation import Observation
 from opentelemetry.util.types import Attributes
 
@@ -173,6 +174,7 @@ def add(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         pass
 
@@ -192,18 +194,20 @@ def add(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
-        return super().add(amount, attributes=attributes)
+        return super().add(amount, attributes=attributes, context=context)
 
 
 class _ProxyCounter(_ProxyInstrument[Counter], Counter):
     def add(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         if self._real_instrument:
-            self._real_instrument.add(amount, attributes)
+            self._real_instrument.add(amount, attributes, context)
 
     def _create_real_instrument(self, meter: "metrics.Meter") -> Counter:
         return meter.create_counter(self._name, self._unit, self._description)
@@ -217,6 +221,7 @@ def add(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         pass
 
@@ -236,18 +241,20 @@ def add(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
-        return super().add(amount, attributes=attributes)
+        return super().add(amount, attributes=attributes, context=context)
 
 
 class _ProxyUpDownCounter(_ProxyInstrument[UpDownCounter], UpDownCounter):
     def add(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         if self._real_instrument:
-            self._real_instrument.add(amount, attributes)
+            self._real_instrument.add(amount, attributes, context)
 
     def _create_real_instrument(self, meter: "metrics.Meter") -> UpDownCounter:
         return meter.create_up_down_counter(
@@ -328,6 +335,7 @@ def record(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         pass
 
@@ -347,18 +355,20 @@ def record(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
-        return super().record(amount, attributes=attributes)
+        return super().record(amount, attributes=attributes, context=context)
 
 
 class _ProxyHistogram(_ProxyInstrument[Histogram], Histogram):
     def record(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         if self._real_instrument:
-            self._real_instrument.record(amount, attributes)
+            self._real_instrument.record(amount, attributes, context)
 
     def _create_real_instrument(self, meter: "metrics.Meter") -> Histogram:
         return meter.create_histogram(
@@ -406,6 +416,7 @@ def set(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         pass
 
@@ -425,8 +436,9 @@ def set(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
-        return super().set(amount, attributes=attributes)
+        return super().set(amount, attributes=attributes, context=context)
 
 
 class _ProxyGauge(
@@ -437,9 +449,10 @@ def set(
         self,
         amount: Union[int, float],
         attributes: Optional[Attributes] = None,
+        context: Optional[Context] = None,
     ) -> None:
         if self._real_instrument:
-            self._real_instrument.set(amount, attributes)
+            self._real_instrument.set(amount, attributes, context)
 
     def _create_real_instrument(self, meter: "metrics.Meter") -> Gauge:
         return meter.create_gauge(self._name, self._unit, self._description)

opentelemetry-api/src/opentelemetry/metrics/_internal/observation.py

@@ -12,8 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import Union
+from typing import Optional, Union
 
+from opentelemetry.context import Context
 from opentelemetry.util.types import Attributes
 
 
@@ -25,13 +26,18 @@ class Observation:
     Args:
         value: The float or int measured value
         attributes: The measurement's attributes
+        context: The measurement's context
     """
 
     def __init__(
-        self, value: Union[int, float], attributes: Attributes = None
+        self,
+        value: Union[int, float],
+        attributes: Attributes = None,
+        context: Optional[Context] = None,
     ) -> None:
         self._value = value
         self._attributes = attributes
+        self._context = context
 
     @property
     def value(self) -> Union[float, int]:
@@ -41,12 +47,17 @@ def value(self) -> Union[float, int]:
     def attributes(self) -> Attributes:
         return self._attributes
 
+    @property
+    def context(self) -> Optional[Context]:
+        return self._context
+
     def __eq__(self, other: object) -> bool:
         return (
             isinstance(other, Observation)
             and self.value == other.value
             and self.attributes == other.attributes
+            and self.context == other.context
         )
 
     def __repr__(self) -> str:
-        return f"Observation(value={self.value}, attributes={self.attributes})"
+        return f"Observation(value={self.value}, attributes={self.attributes}, context={self.context})"

opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py

@@ -15,6 +15,15 @@
 
 from opentelemetry.sdk.metrics._internal import Meter, MeterProvider
 from opentelemetry.sdk.metrics._internal.exceptions import MetricsTimeoutError
+from opentelemetry.sdk.metrics._internal.exemplar import (
+    AlignedHistogramBucketExemplarReservoir,
+    AlwaysOffExemplarFilter,
+    AlwaysOnExemplarFilter,
+    ExemplarFilter,
+    ExemplarReservoir,
+    SimpleFixedSizeExemplarReservoir,
+    TraceBasedExemplarFilter,
+)
 from opentelemetry.sdk.metrics._internal.instrument import Counter
 from opentelemetry.sdk.metrics._internal.instrument import Gauge as _Gauge
 from opentelemetry.sdk.metrics._internal.instrument import (
@@ -26,6 +35,11 @@
 )
 
 __all__ = [
+    "AlignedHistogramBucketExemplarReservoir",
+    "AlwaysOnExemplarFilter",
+    "AlwaysOffExemplarFilter",
+    "ExemplarFilter",
+    "ExemplarReservoir",
     "Meter",
     "MeterProvider",
     "MetricsTimeoutError",
@@ -35,5 +49,7 @@
     "ObservableCounter",
     "ObservableGauge",
     "ObservableUpDownCounter",
+    "SimpleFixedSizeExemplarReservoir",
     "UpDownCounter",
+    "TraceBasedExemplarFilter",
 ]

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/__init__.py

@@ -35,6 +35,10 @@
 from opentelemetry.metrics import _Gauge as APIGauge
 from opentelemetry.sdk.environment_variables import OTEL_SDK_DISABLED
 from opentelemetry.sdk.metrics._internal.exceptions import MetricsTimeoutError
+from opentelemetry.sdk.metrics._internal.exemplar import (
+    ExemplarFilter,
+    TraceBasedExemplarFilter,
+)
 from opentelemetry.sdk.metrics._internal.instrument import (
     _Counter,
     _Gauge,
@@ -380,7 +384,8 @@ def __init__(
         metric_readers: Sequence[
             "opentelemetry.sdk.metrics.export.MetricReader"
         ] = (),
-        resource: Resource = None,
+        resource: Optional[Resource] = None,
+        exemplar_filter: Optional[ExemplarFilter] = None,
         shutdown_on_exit: bool = True,
         views: Sequence["opentelemetry.sdk.metrics.view.View"] = (),
     ):
@@ -390,6 +395,11 @@ def __init__(
         if resource is None:
             resource = Resource.create({})
         self._sdk_config = SdkConfiguration(
+            exemplar_filter=(
+                TraceBasedExemplarFilter()
+                if exemplar_filter is None
+                else exemplar_filter
+            ),
             resource=resource,
             metric_readers=metric_readers,
             views=views,

opentelemetry-sdk/src/opentelemetry/sdk/metrics/_internal/_view_instrument_match.py

@@ -52,12 +52,20 @@ def __init__(
         )
         if not isinstance(self._view._aggregation, DefaultAggregation):
             self._aggregation = self._view._aggregation._create_aggregation(
-                self._instrument, None, 0
+                self._instrument,
+                None,
+                self._view._exemplar_reservoir_factory,
+                0,
             )
         else:
             self._aggregation = self._instrument_class_aggregation[
                 self._instrument.__class__
-            ]._create_aggregation(self._instrument, None, 0)
+            ]._create_aggregation(
+                self._instrument,
+                None,
+                self._view._exemplar_reservoir_factory,
+                0,
+            )
 
     def conflicts(self, other: "_ViewInstrumentMatch") -> bool:
         # pylint: disable=protected-access
@@ -81,7 +89,9 @@ def conflicts(self, other: "_ViewInstrumentMatch") -> bool:
         return result
 
     # pylint: disable=protected-access
-    def consume_measurement(self, measurement: Measurement) -> None:
+    def consume_measurement(
+        self, measurement: Measurement, should_sample_exemplar: bool = True
+    ) -> None:
 
         if self._view._attribute_keys is not None:
 
@@ -107,6 +117,7 @@ def consume_measurement(self, measurement: Measurement) -> None:
                             self._view._aggregation._create_aggregation(
                                 self._instrument,
                                 attributes,
+                                self._view._exemplar_reservoir_factory,
                                 self._start_time_unix_nano,
                             )
                         )
@@ -116,11 +127,14 @@ def consume_measurement(self, measurement: Measurement) -> None:
                         ]._create_aggregation(
                             self._instrument,
                             attributes,
+                            self._view._exemplar_reservoir_factory,
                             self._start_time_unix_nano,
                         )
                     self._attributes_aggregation[aggr_key] = aggregation
 
-        self._attributes_aggregation[aggr_key].aggregate(measurement)
+        self._attributes_aggregation[aggr_key].aggregate(
+            measurement, should_sample_exemplar
+        )
 
     def collect(
         self,