Bring metrics exemplar filter and reservoir out of `internal` #7636

breedx-splk · 2025-09-03T17:40:26Z

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 · 2025-09-03T17:53:20Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.01%. Comparing base (90a2bb6) to head (eb19261).
⚠️ Report is 92 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 · 2025-09-08T20:14:55Z

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/exemplar/ExemplarReservoir.java

- * <p>This class is internal and is hence not for public use. Its APIs are unstable and can change
- * at any time.
 */
 public interface ExemplarReservoir<T extends ExemplarData> {


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.

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

cool. thanks for checking. 👍🏽

But its not currently exposed in any of our APIs. I think we have some work to do on the ExemplarReservoir interface before exposing publicly. In particular, all the static methods for creating ExemplarReservoir (i.e. ExemplarReservoir#doubleNoSamples() are specific to either long or double. Views are generic (i.e. a single view can apply to both long and double instruments) so we'll need to somehow bridge this.

See PR to fix this here: #7742

jkwatson

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

zeitlinger · 2025-09-11T10:34:48Z

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 · 2025-09-11T17:34:06Z

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

zeitlinger · 2025-09-17T08:49:57Z

@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 · 2025-09-17T18:06:57Z

@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 · 2025-09-18T07:17:36Z

Created #7667

jack-berg · 2025-09-19T19:39:00Z

docs/apidiffs/current_vs_latest/opentelemetry-sdk-metrics.txt

+	+++  NEW INTERFACE: io.opentelemetry.sdk.metrics.exemplar.ExemplarFilter
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) boolean shouldSampleMeasurement(long, io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+	+++  NEW METHOD: PUBLIC(+) boolean shouldSampleMeasurement(double, io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)


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.

Ok, so if I understand this correctly --

some spec version happened

we built an implementation

the spec changed (as described above) and we didn't change code

the spec went stable

Stable ExemplarFilter in SdkMeterProviderBuilder #7503 was filed

I made this PR

@jack-berg noticed that our implementation wasn't matching the spec

If I have that right, then it sounds like the course of action is for me to close this PR and copy the above comment into a new issue for us to fix, and make #7503 blocked/depend on that new issue? Yeah?

Or you can leave this PR open / draft while separately pursue resolving the spec <-> opentelemetry-java deviation, and then rebase this PR.

robsunday · 2025-09-29T07:13:59Z

...toconfigure/src/main/java/io/opentelemetry/sdk/autoconfigure/MeterProviderConfiguration.java

+        return ExemplarFilter.alwaysOn();
+      case "trace_based":
+      default:
+        return ExemplarFilter.traceBased();


I think it would be good to log unrecognized exemplar filter kind, unless there is some reason not to do that.

This is not new code. We would do that in a follow-up PR if wanted.

jack-berg

We still have some work to do before promoting these APIs to public. See my comments. Marking this as "Request Changes" so it doesn't accidentally get merged.

jack-berg · 2025-10-18T18:30:10Z

Closing this because I made changes to exemplar reservoir that create a bunch of merge conflicts and opened an alternative, narrower version in #7768. Thanks for pushing on this @breedx-splk - its long overdue.

breedx-splk requested a review from a team as a code owner September 3, 2025 17:40

breedx-splk added metrics spec:metrics labels Sep 3, 2025

jkwatson reviewed Sep 8, 2025

View reviewed changes

jkwatson approved these changes Sep 8, 2025

View reviewed changes

breedx-splk added 8 commits September 10, 2025 09:12

remove internal/experimental wording around exemplar stuff

e5f07c1

make setter public and remove experimental note

0f5e0a8

deprecate util method and suggest calling it directly

fca1416

repackage exemplars (make non-internal)

ad832a2

repackage exemplars tests

6b0589a

add test to ensure backwards compat

3269221

spotless

b96c52c

fix up remaining usages, regen sdk apidiff

44887f9

breedx-splk force-pushed the unhide_exemplars branch from 5bc1732 to 44887f9 Compare September 10, 2025 16:13

manually update versions (perhaps this helps, who knows)

eb19261

zeitlinger mentioned this pull request Sep 18, 2025

declarative config: metrics exemplar filter #7667

Open

jack-berg reviewed Sep 19, 2025

View reviewed changes

robsunday reviewed Sep 29, 2025

View reviewed changes

jkwatson self-requested a review October 9, 2025 19:51

jack-berg mentioned this pull request Oct 10, 2025

Remove ExemplarReservoir generic type #7742

Closed

jack-berg requested changes Oct 10, 2025

View reviewed changes

jack-berg mentioned this pull request Oct 18, 2025

Stabilize ExemplarFilter #7768

Open

jack-berg closed this Oct 18, 2025

Bring metrics exemplar filter and reservoir out of internal #7636

Bring metrics exemplar filter and reservoir out of internal #7636

Uh oh!

Conversation

breedx-splk commented Sep 3, 2025

Uh oh!

codecov bot commented Sep 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jkwatson left a comment

Choose a reason for hiding this comment

Uh oh!

zeitlinger commented Sep 11, 2025

Uh oh!

breedx-splk commented Sep 11, 2025

Uh oh!

zeitlinger commented Sep 17, 2025

Uh oh!

breedx-splk commented Sep 17, 2025

Uh oh!

zeitlinger commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jack-berg left a comment

Choose a reason for hiding this comment

Uh oh!

jack-berg commented Oct 18, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Bring metrics exemplar filter and reservoir out of `internal` #7636

Bring metrics exemplar filter and reservoir out of `internal` #7636

codecov bot commented Sep 3, 2025 •

edited

Loading

zeitlinger commented Sep 18, 2025 •

edited

Loading