Bring metrics exemplar filter and reservoir out of internal

[breedx-splk]

Resolves #7503

Back in 2022 the metrics ExemplarFilter (and reservoir) were hidden in an internal package (in #4276) while waiting on the spec to stabilize. Now that Exemplars are marked as stable, it should be safe to now bring these out of the "internal" packaging.

I left the existing utility method that invoked the package private method using reflection, but marked it as deprecated. Our normal process is to give a release with the deprecation before removing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.01%. Comparing base (90a2bb6) to head (eb19261).
⚠️ Report is 7 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #7636   +/-   ##
=========================================
  Coverage     90.01%   90.01%           
- Complexity     7090     7091    +1     
=========================================
  Files           803      803           
  Lines         21443    21443           
  Branches       2092     2092           
=========================================
  Hits          19301    19301           
  Misses         1477     1477           
  Partials        665      665           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jkwatson]

Does this guy need to be part of our public API? Do we want to allow people to create their own custom reservoir implementations? Just making sure we're not opening things up a bit too much before we know this is something that we want people to be able to customize.

[breedx-splk]

Welp https://opentelemetry.io/docs/specs/otel/metrics/sdk/#custom-exemplarreservoir 🙈

[jkwatson]

cool. thanks for checking. 👍🏽

[jkwatson]

Thanks! I'd like @jack-berg to verify this API is good to go, then we should be good to merge.

[zeitlinger]

Declarative config is missing - not sure if if was forgotten before - but we should add it now:

Subject: [PATCH] rebase
---
Index: sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/MeterProviderFactory.java
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/MeterProviderFactory.java b/sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/MeterProviderFactory.java
--- a/sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/MeterProviderFactory.java	(revision eb19261e3e21009d71bd3bf356c747f8cff65c5b)
+++ b/sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/MeterProviderFactory.java	(date 1757586811644)
@@ -7,6 +7,7 @@
 
 import static io.opentelemetry.sdk.extension.incubator.fileconfig.FileConfigUtil.requireNonNull;
 
+import io.opentelemetry.api.incubator.config.DeclarativeConfigException;
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ExperimentalMeterConfigModel;
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ExperimentalMeterConfiguratorModel;
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ExperimentalMeterMatcherAndConfigModel;
@@ -19,6 +20,7 @@
 import io.opentelemetry.sdk.internal.ScopeConfiguratorBuilder;
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
 import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
+import io.opentelemetry.sdk.metrics.exemplar.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.export.CardinalityLimitSelector;
 import io.opentelemetry.sdk.metrics.internal.MeterConfig;
 import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
@@ -39,6 +41,11 @@
       MeterProviderModel model, DeclarativeConfigContext context) {
     SdkMeterProviderBuilder builder = SdkMeterProvider.builder();
 
+    MeterProviderModel.ExemplarFilter exemplarFilter = model.getExemplarFilter();
+    if (exemplarFilter != null) {
+      builder.setExemplarFilter(getExemplarFilter(exemplarFilter));
+    }
+
     List<MetricReaderModel> readerModels = model.getReaders();
     if (readerModels != null) {
       readerModels.forEach(
@@ -98,6 +105,19 @@
     return builder;
   }
 
+  private ExemplarFilter getExemplarFilter(MeterProviderModel.ExemplarFilter filter) {
+    switch (filter) {
+      case ALWAYS_ON:
+        return ExemplarFilter.alwaysOn();
+      case ALWAYS_OFF:
+        return ExemplarFilter.alwaysOff();
+      case TRACE_BASED:
+        return ExemplarFilter.traceBased();
+      default:
+        throw new DeclarativeConfigException("Unknown exemplar filter: " + filter);
+    }
+  }
+
   private static class MeterConfigFactory
       implements Factory<ExperimentalMeterConfigModel, MeterConfig> {

[breedx-splk]

@zeitlinger sorry I'm not following. What does that have to do with this change?

[zeitlinger]

@zeitlinger sorry I'm not following. What does that have to do with this change?

just noticed that while reviewing the change - declarative config support can only be added with this change, because it makes the builder method public - or we do a follow-up PR

[breedx-splk]

@zeitlinger sorry I'm not following. What does that have to do with this change?

just noticed that while reviewing the change - declarative config support can only be added with this change, because it makes the builder method public - or we do a follow-up PR

Ah ok. Well I'd prefer a follow-up PR if that's ok with you.

[zeitlinger]

Created #7667

[jack-berg]

Some changes were made from the original exemplar design vs. what was ultimately marked stable. Notably, ExemplarFilter is no longer a extension plugin interface. See the difference in language between ExemplarFilter and ExemplarReservoir which is a extension plugin interface:

• ExemplarFilter: "The ExemplarFilter configuration MUST allow users to select between one of the built-in ExemplarFilters."
• ExemplarReservoir: "The ExemplarReservoir interface MUST provide a method to offer measurements to the reservoir and another to collect accumulated Exemplars."

We need to adjust our API for ExemplarFilter accordingly. Its actually conceptually similar to our Aggregation: modeled as an interface with no methods, with the actual meaningful interface / methods in the internal AggregationFactory.