[EXEMPLAR] Update ExemplarFilter and ExemplarReservoir for spec

CHANGELOG.md

@@ -78,6 +78,8 @@ Increment the:
   [#2631](https://github.com/open-telemetry/opentelemetry-cpp/pull/2631)
 * [SDK] DefaultLogHandler to print errors to std::cerr, add LogLevel::None
   [#2622](https://github.com/open-telemetry/opentelemetry-cpp/pull/2622)
+* [SDK] Update ExemplarFilter and ExemplarReservoir for spec
+  [#2372](https://github.com/open-telemetry/opentelemetry-cpp/pull/2372)
 * [SEMANTIC CONVENTIONS] Upgrade to semantic convention 1.25.0
   [#2633](https://github.com/open-telemetry/opentelemetry-cpp/pull/2633)
 * [DOC] Add readme and examples for OTLP FILE exporters.
@@ -124,6 +126,13 @@ Important changes:
     * Numbering of log levels like OTEL_INTERNAL_LOG_LEVEL_ERROR
       has changed, which requires to rebuild, as the SDK ABI differs.
 
+Notes on experimental features:
+
+* [#2372](https://github.com/open-telemetry/opentelemetry-cpp/issues/2372)
+  introduced `MeterProvider::SetExemplar()` which accepts en
+  `ExemplarFilterType` enumeration with `kAlwaysOff`, `kAlwaysOn` and
+  `kTraceBased`.
+
 ## [1.14.2] 2024-02-27
 
 * [SDK] Fix observable attributes drop

sdk/include/opentelemetry/sdk/metrics/exemplar/histogram_exemplar_reservoir.h → sdk/include/opentelemetry/sdk/metrics/exemplar/aligned_histogram_bucket_exemplar_reservoir.h

@@ -3,15 +3,18 @@
 
 #pragma once
 
-#include <memory>
-#include <vector>
+#ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
 
-#include "opentelemetry/sdk/metrics/data/exemplar_data.h"
-#include "opentelemetry/sdk/metrics/exemplar/filter.h"
-#include "opentelemetry/sdk/metrics/exemplar/fixed_size_exemplar_reservoir.h"
-#include "opentelemetry/sdk/metrics/exemplar/reservoir.h"
-#include "opentelemetry/sdk/metrics/exemplar/reservoir_cell_selector.h"
-#include "opentelemetry/version.h"
+#  include <memory>
+#  include <vector>
+
+#  include "opentelemetry/sdk/common/global_log_handler.h"
+#  include "opentelemetry/sdk/metrics/data/exemplar_data.h"
+#  include "opentelemetry/sdk/metrics/exemplar/filter_type.h"
+#  include "opentelemetry/sdk/metrics/exemplar/fixed_size_exemplar_reservoir.h"
+#  include "opentelemetry/sdk/metrics/exemplar/reservoir.h"
+#  include "opentelemetry/sdk/metrics/exemplar/reservoir_cell_selector.h"
+#  include "opentelemetry/version.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
 namespace common
@@ -29,7 +32,7 @@ namespace sdk
 namespace metrics
 {
 
-class HistogramExemplarReservoir : public FixedSizeExemplarReservoir
+class AlignedHistogramBucketExemplarReservoir : public FixedSizeExemplarReservoir
 {
 
 public:
@@ -39,11 +42,11 @@ class HistogramExemplarReservoir : public FixedSizeExemplarReservoir
     return std::shared_ptr<ReservoirCellSelector>{new HistogramCellSelector(boundaries)};
   }
 
-  HistogramExemplarReservoir(size_t size,
-                             std::shared_ptr<ReservoirCellSelector> reservoir_cell_selector,
-                             std::shared_ptr<ExemplarData> (ReservoirCell::*map_and_reset_cell)(
-                                 const opentelemetry::sdk::common::OrderedAttributeMap &attributes))
-      : FixedSizeExemplarReservoir(size, reservoir_cell_selector, map_and_reset_cell)
+  AlignedHistogramBucketExemplarReservoir(
+      size_t size,
+      std::shared_ptr<ReservoirCellSelector> reservoir_cell_selector,
+      MapAndResetCellType map_and_reset_cell)
+      : FixedSizeExemplarReservoir(size + 1, reservoir_cell_selector, map_and_reset_cell)
   {}
 
   class HistogramCellSelector : public ReservoirCellSelector
@@ -72,7 +75,9 @@ class HistogramExemplarReservoir : public FixedSizeExemplarReservoir
           return static_cast<int>(i);
         }
       }
-      return -1;
+
+      // The bucket at max_size is for values greater than the last boundary
+      return static_cast<int>(max_size);
     }
 
   private:
@@ -87,3 +92,5 @@ class HistogramExemplarReservoir : public FixedSizeExemplarReservoir
 }  // namespace metrics
 }  // namespace sdk
 OPENTELEMETRY_END_NAMESPACE
+
+#endif  // ENABLE_METRICS_EXEMPLAR_PREVIEW

sdk/include/opentelemetry/sdk/metrics/exemplar/filter_type.h

@@ -0,0 +1,46 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+#pragma once
+
+#ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
+
+#  include <memory>
+
+#  include "opentelemetry/sdk/metrics/state/filtered_ordered_attribute_map.h"
+#  include "opentelemetry/version.h"
+
+OPENTELEMETRY_BEGIN_NAMESPACE
+namespace context
+{
+class Context;
+}  // namespace context
+
+namespace sdk
+{
+namespace common
+{
+class OrderedAttributeMap;
+}  // namespace common
+
+namespace metrics
+{
+using MetricAttributes = opentelemetry::sdk::metrics::FilteredOrderedAttributeMap;
+
+/**
+ * Exemplar filter type is used to pre-filter measurements before attempting to store them in a
+ * reservoir.
+ * https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#exemplarfilter
+ */
+enum class ExemplarFilterType : uint8_t
+{
+  kAlwaysOff,
+  kAlwaysOn,
+  kTraceBased
+};
+
+}  // namespace metrics
+}  // namespace sdk
+OPENTELEMETRY_END_NAMESPACE
+
+#endif  // ENABLE_METRICS_EXEMPLAR_PREVIEW

sdk/include/opentelemetry/sdk/metrics/exemplar/fixed_size_exemplar_reservoir.h

@@ -3,16 +3,18 @@
 
 #pragma once
 
-#include <memory>
-#include <vector>
+#ifdef ENABLE_METRICS_EXEMPLAR_PREVIEW
 
-#include "opentelemetry/context/context.h"
-#include "opentelemetry/nostd/function_ref.h"
-#include "opentelemetry/nostd/shared_ptr.h"
-#include "opentelemetry/sdk/common/attribute_utils.h"
-#include "opentelemetry/sdk/metrics/exemplar/reservoir.h"
-#include "opentelemetry/sdk/metrics/exemplar/reservoir_cell.h"
-#include "opentelemetry/sdk/metrics/exemplar/reservoir_cell_selector.h"
+#  include <memory>
+#  include <vector>
+
+#  include "opentelemetry/context/context.h"
+#  include "opentelemetry/nostd/function_ref.h"
+#  include "opentelemetry/nostd/shared_ptr.h"
+#  include "opentelemetry/sdk/common/attribute_utils.h"
+#  include "opentelemetry/sdk/metrics/exemplar/reservoir.h"
+#  include "opentelemetry/sdk/metrics/exemplar/reservoir_cell.h"
+#  include "opentelemetry/sdk/metrics/exemplar/reservoir_cell_selector.h"
 
 OPENTELEMETRY_BEGIN_NAMESPACE
 namespace sdk
@@ -26,13 +28,14 @@ class FixedSizeExemplarReservoir : public ExemplarReservoir
 public:
   FixedSizeExemplarReservoir(size_t size,
                              std::shared_ptr<ReservoirCellSelector> reservoir_cell_selector,
-                             std::shared_ptr<ExemplarData> (ReservoirCell::*map_and_reset_cell)(
-                                 const opentelemetry::sdk::common::OrderedAttributeMap &attributes))
+                             MapAndResetCellType map_and_reset_cell)
       : storage_(size),
         reservoir_cell_selector_(reservoir_cell_selector),
         map_and_reset_cell_(map_and_reset_cell)
   {}
 
+  using ExemplarReservoir::OfferMeasurement;
+
   void OfferMeasurement(
       int64_t value,
       const MetricAttributes &attributes,
@@ -95,10 +98,11 @@ class FixedSizeExemplarReservoir : public ExemplarReservoir
   explicit FixedSizeExemplarReservoir() = default;
   std::vector<ReservoirCell> storage_;
   std::shared_ptr<ReservoirCellSelector> reservoir_cell_selector_;
-  std::shared_ptr<ExemplarData> (ReservoirCell::*map_and_reset_cell_)(
-      const opentelemetry::sdk::common::OrderedAttributeMap &attributes);
+  MapAndResetCellType map_and_reset_cell_;
 };
 
 }  // namespace metrics
 }  // namespace sdk
 OPENTELEMETRY_END_NAMESPACE
+
+#endif  // ENABLE_METRICS_EXEMPLAR_PREVIEW