Stabilize ExemplarFilter

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

@@ -1,2 +1,10 @@
 Comparing source compatibility of opentelemetry-sdk-metrics-1.56.0-SNAPSHOT.jar against opentelemetry-sdk-metrics-1.55.0.jar
-No changes.
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.metrics.ExemplarFilter  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.ExemplarFilter alwaysOff()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.ExemplarFilter alwaysOn()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.ExemplarFilter traceBased()
+***  MODIFIED CLASS: PUBLIC FINAL io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder setExemplarFilter(io.opentelemetry.sdk.metrics.ExemplarFilter)

integration-tests/otlp/src/main/java/io/opentelemetry/integrationtest/OtlpExporterIntegrationTest.java

@@ -65,12 +65,10 @@
 import io.opentelemetry.sdk.logs.SdkLoggerProvider;
 import io.opentelemetry.sdk.logs.export.BatchLogRecordProcessor;
 import io.opentelemetry.sdk.logs.export.LogRecordExporter;
+import io.opentelemetry.sdk.metrics.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
-import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
 import io.opentelemetry.sdk.metrics.export.MetricExporter;
 import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
-import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import io.opentelemetry.sdk.resources.Resource;
 import io.opentelemetry.sdk.trace.IdGenerator;
 import io.opentelemetry.sdk.trace.SdkTracerProvider;
@@ -461,18 +459,16 @@ void testOtlpHttpMetricExport_mtls() throws Exception {
   }
 
   private static void testMetricExport(MetricExporter metricExporter) {
-    SdkMeterProviderBuilder meterProviderBuilder =
+    SdkMeterProvider meterProvider =
         SdkMeterProvider.builder()
             .setResource(RESOURCE)
             .registerMetricReader(
                 PeriodicMetricReader.builder(metricExporter)
                     .setInterval(Duration.ofSeconds(Integer.MAX_VALUE))
-                    .build());
-
-    // Enable alwaysOn exemplar filter, instead of default traceBased filter
-    SdkMeterProviderUtil.setExemplarFilter(meterProviderBuilder, ExemplarFilter.alwaysOn());
-
-    SdkMeterProvider meterProvider = meterProviderBuilder.build();
+                    .build())
+            // Enable alwaysOn exemplar filter, instead of default traceBased filter
+            .setExemplarFilter(ExemplarFilter.alwaysOn())
+            .build();
 
     Meter meter = meterProvider.meterBuilder(OtlpExporterIntegrationTest.class.getName()).build();
 

sdk-extensions/autoconfigure/src/main/java/io/opentelemetry/sdk/autoconfigure/MeterProviderConfiguration.java

@@ -9,11 +9,10 @@
 import io.opentelemetry.sdk.autoconfigure.spi.ConfigProperties;
 import io.opentelemetry.sdk.autoconfigure.spi.ConfigurationException;
 import io.opentelemetry.sdk.autoconfigure.spi.internal.DefaultConfigProperties;
+import io.opentelemetry.sdk.metrics.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
 import io.opentelemetry.sdk.metrics.export.MetricExporter;
 import io.opentelemetry.sdk.metrics.export.MetricReader;
-import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.internal.state.MetricStorage;
 import java.io.Closeable;
 import java.util.Collections;
@@ -43,14 +42,14 @@ static void configureMeterProvider(
         config.getString("otel.metrics.exemplar.filter", "trace_based").toLowerCase(Locale.ROOT);
     switch (exemplarFilter) {
       case "always_off":
-        SdkMeterProviderUtil.setExemplarFilter(meterProviderBuilder, ExemplarFilter.alwaysOff());
+        meterProviderBuilder.setExemplarFilter(ExemplarFilter.alwaysOff());
         break;
       case "always_on":
-        SdkMeterProviderUtil.setExemplarFilter(meterProviderBuilder, ExemplarFilter.alwaysOn());
+        meterProviderBuilder.setExemplarFilter(ExemplarFilter.alwaysOn());
         break;
       case "trace_based":
       default:
-        SdkMeterProviderUtil.setExemplarFilter(meterProviderBuilder, ExemplarFilter.traceBased());
+        meterProviderBuilder.setExemplarFilter(ExemplarFilter.traceBased());
         break;
     }
 

sdk-extensions/autoconfigure/src/test/java/io/opentelemetry/sdk/autoconfigure/MeterProviderConfigurationTest.java

@@ -14,7 +14,7 @@
 import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
 import io.opentelemetry.sdk.metrics.internal.exemplar.AlwaysOffExemplarFilter;
 import io.opentelemetry.sdk.metrics.internal.exemplar.AlwaysOnExemplarFilter;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
+import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilterInternal;
 import io.opentelemetry.sdk.metrics.internal.exemplar.TraceBasedExemplarFilter;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -45,7 +45,8 @@ void configureMeterProvider_ConfiguresExemplarFilter() {
         .isInstanceOf(AlwaysOnExemplarFilter.class);
   }
 
-  private static ObjectAssert<ExemplarFilter> assertExemplarFilter(Map<String, String> config) {
+  private static ObjectAssert<ExemplarFilterInternal> assertExemplarFilter(
+      Map<String, String> config) {
     Map<String, String> configWithDefault = new HashMap<>(config);
     configWithDefault.put("otel.metrics.exporter", "none");
     SdkMeterProviderBuilder builder = SdkMeterProvider.builder();
@@ -57,6 +58,7 @@ private static ObjectAssert<ExemplarFilter> assertExemplarFilter(Map<String, Str
         (a, b) -> a,
         new ArrayList<>());
     return assertThat(builder)
-        .extracting("exemplarFilter", as(InstanceOfAssertFactories.type(ExemplarFilter.class)));
+        .extracting(
+            "exemplarFilter", as(InstanceOfAssertFactories.type(ExemplarFilterInternal.class)));
   }
 }

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/ExemplarFilterFactory.java

@@ -7,7 +7,7 @@
 
 import io.opentelemetry.api.incubator.config.DeclarativeConfigException;
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.MeterProviderModel;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
+import io.opentelemetry.sdk.metrics.ExemplarFilter;
 
 final class ExemplarFilterFactory
     implements Factory<MeterProviderModel.ExemplarFilter, ExemplarFilter> {

sdk-extensions/incubator/src/main/java/io/opentelemetry/sdk/extension/incubator/fileconfig/MeterProviderFactory.java

@@ -97,8 +97,8 @@ public SdkMeterProviderBuilder create(
 
     MeterProviderModel.ExemplarFilter exemplarFilterModel = model.getExemplarFilter();
     if (exemplarFilterModel != null) {
-      SdkMeterProviderUtil.setExemplarFilter(
-          builder, ExemplarFilterFactory.getInstance().create(exemplarFilterModel, context));
+      builder.setExemplarFilter(
+          ExemplarFilterFactory.getInstance().create(exemplarFilterModel, context));
     }
 
     return builder;

sdk-extensions/incubator/src/test/java/io/opentelemetry/sdk/extension/incubator/fileconfig/ExemplarFilterFactoryTest.java

@@ -9,7 +9,7 @@
 import static org.mockito.Mockito.mock;
 
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.MeterProviderModel;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
+import io.opentelemetry.sdk.metrics.ExemplarFilter;
 import java.util.stream.Stream;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;

sdk-extensions/incubator/src/test/java/io/opentelemetry/sdk/extension/incubator/fileconfig/MeterProviderFactoryTest.java

@@ -5,7 +5,6 @@
 
 package io.opentelemetry.sdk.extension.incubator.fileconfig;
 
-import static io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil.setExemplarFilter;
 import static io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil.setMeterConfigurator;
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.assertThat;
 
@@ -25,12 +24,12 @@
 import io.opentelemetry.sdk.extension.incubator.fileconfig.internal.model.ViewStreamModel;
 import io.opentelemetry.sdk.internal.ScopeConfigurator;
 import io.opentelemetry.sdk.internal.ScopeConfiguratorBuilder;
+import io.opentelemetry.sdk.metrics.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.InstrumentSelector;
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
 import io.opentelemetry.sdk.metrics.View;
 import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
 import io.opentelemetry.sdk.metrics.internal.MeterConfig;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import java.io.Closeable;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -94,16 +93,14 @@ private static Stream<Arguments> createArguments() {
                                     .withConfig(
                                         new ExperimentalMeterConfigModel().withDisabled(false)))))
                 .withExemplarFilter(MeterProviderModel.ExemplarFilter.ALWAYS_ON),
-            setExemplarFilter(
-                    setMeterConfigurator(
-                        SdkMeterProvider.builder(),
-                        ScopeConfigurator.<MeterConfig>builder()
-                            .setDefault(MeterConfig.disabled())
-                            .addCondition(
-                                ScopeConfiguratorBuilder.nameMatchesGlob("foo"),
-                                MeterConfig.enabled())
-                            .build()),
-                    ExemplarFilter.alwaysOn())
+            setMeterConfigurator(
+                    SdkMeterProvider.builder(),
+                    ScopeConfigurator.<MeterConfig>builder()
+                        .setDefault(MeterConfig.disabled())
+                        .addCondition(
+                            ScopeConfiguratorBuilder.nameMatchesGlob("foo"), MeterConfig.enabled())
+                        .build())
+                .setExemplarFilter(ExemplarFilter.alwaysOn())
                 .registerMetricReader(
                     PeriodicMetricReader.builder(OtlpHttpMetricExporter.getDefault()).build())
                 .registerView(

sdk/metrics/src/jmh/java/io/opentelemetry/sdk/metrics/TestSdk.java

@@ -9,7 +9,6 @@
 import io.opentelemetry.api.metrics.MeterProvider;
 import io.opentelemetry.api.trace.Tracer;
 import io.opentelemetry.sdk.common.Clock;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import io.opentelemetry.sdk.resources.Resource;
 import io.opentelemetry.sdk.testing.exporter.InMemoryMetricReader;
 import io.opentelemetry.sdk.trace.SdkTracerProvider;

sdk/metrics/src/jmh/java/io/opentelemetry/sdk/metrics/internal/aggregator/HistogramCollectBenchmark.java

@@ -9,15 +9,13 @@
 import io.opentelemetry.api.metrics.DoubleHistogram;
 import io.opentelemetry.sdk.common.CompletableResultCode;
 import io.opentelemetry.sdk.metrics.Aggregation;
+import io.opentelemetry.sdk.metrics.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.InstrumentType;
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
-import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
 import io.opentelemetry.sdk.metrics.data.AggregationTemporality;
 import io.opentelemetry.sdk.metrics.data.MetricData;
 import io.opentelemetry.sdk.metrics.export.MetricExporter;
 import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
-import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Collection;
@@ -64,7 +62,7 @@ public static class ThreadState {
 
     @Setup
     public void setup() {
-      SdkMeterProviderBuilder builder =
+      SdkMeterProvider sdkMeterProvider =
           SdkMeterProvider.builder()
               .registerMetricReader(
                   PeriodicMetricReader.builder(
@@ -74,10 +72,11 @@ public void setup() {
                               aggregationTemporality, aggregationGenerator.aggregation))
                       // Effectively disable periodic reading so reading is only done on #flush()
                       .setInterval(Duration.ofSeconds(Integer.MAX_VALUE))
-                      .build());
-      // Disable exemplars
-      SdkMeterProviderUtil.setExemplarFilter(builder, ExemplarFilter.alwaysOff());
-      sdkMeterProvider = builder.build();
+                      .build())
+              // Disable exemplars
+              .setExemplarFilter(ExemplarFilter.alwaysOff())
+              .build();
+
       histogram = sdkMeterProvider.get("meter").histogramBuilder("histogram").build();
 
       random = new Random();

sdk/metrics/src/jmhBasedTest/java/io/opentelemetry/sdk/metrics/internal/state/InstrumentGarbageCollectionBenchmark.java

@@ -7,12 +7,11 @@
 
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.sdk.common.export.MemoryMode;
+import io.opentelemetry.sdk.metrics.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
 import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
 import io.opentelemetry.sdk.metrics.data.AggregationTemporality;
 import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
-import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.internal.state.TestInstrumentType.InstrumentTester;
 import io.opentelemetry.sdk.metrics.internal.state.TestInstrumentType.TestInstrumentsState;
 import java.time.Duration;
@@ -96,7 +95,7 @@ public void setup() {
       attributesList = AttributesGenerator.generate(cardinality);
 
       // Disable exemplars
-      SdkMeterProviderUtil.setExemplarFilter(builder, ExemplarFilter.alwaysOff());
+      builder.setExemplarFilter(ExemplarFilter.alwaysOff());
 
       sdkMeterProvider = builder.build();
       testInstrumentsState =

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/ExemplarFilter.java

@@ -0,0 +1,41 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.metrics;
+
+import io.opentelemetry.context.Context;
+import io.opentelemetry.sdk.metrics.internal.exemplar.AlwaysOffExemplarFilter;
+import io.opentelemetry.sdk.metrics.internal.exemplar.AlwaysOnExemplarFilter;
+import io.opentelemetry.sdk.metrics.internal.exemplar.DoubleExemplarReservoir;
+import io.opentelemetry.sdk.metrics.internal.exemplar.LongExemplarReservoir;
+import io.opentelemetry.sdk.metrics.internal.exemplar.TraceBasedExemplarFilter;
+
+/**
+ * Exemplar filters are used to pre-filter measurements before attempting to store them in a
+ * reservoir ({@link DoubleExemplarReservoir}, {@link LongExemplarReservoir}.
+ *
+ * @see SdkMeterProviderBuilder#setExemplarFilter(ExemplarFilter)
+ */
+// TODO(jack-berg): Have methods when custom filters are supported.
+@SuppressWarnings("InterfaceWithOnlyStatics")
+public interface ExemplarFilter {
+  /**
+   * A filter that only accepts measurements where there is a {@code Span} in {@link Context} that
+   * is being sampled.
+   */
+  static ExemplarFilter traceBased() {
+    return TraceBasedExemplarFilter.getInstance();
+  }
+
+  /** A filter which makes all measurements eligible for being an exemplar. */
+  static ExemplarFilter alwaysOn() {
+    return AlwaysOnExemplarFilter.getInstance();
+  }
+
+  /** A filter which makes no measurements eligible for being an exemplar. */
+  static ExemplarFilter alwaysOff() {
+    return AlwaysOffExemplarFilter.getInstance();
+  }
+}

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkMeterProvider.java

@@ -21,7 +21,7 @@
 import io.opentelemetry.sdk.metrics.export.MetricReader;
 import io.opentelemetry.sdk.metrics.internal.MeterConfig;
 import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
+import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilterInternal;
 import io.opentelemetry.sdk.metrics.internal.export.RegisteredReader;
 import io.opentelemetry.sdk.metrics.internal.state.MeterProviderSharedState;
 import io.opentelemetry.sdk.metrics.internal.view.RegisteredView;
@@ -67,7 +67,7 @@ public static SdkMeterProviderBuilder builder() {
       List<MetricProducer> metricProducers,
       Clock clock,
       Resource resource,
-      ExemplarFilter exemplarFilter,
+      ExemplarFilterInternal exemplarFilter,
       ScopeConfigurator<MeterConfig> meterConfigurator) {
     long startEpochNanos = clock.now();
     this.registeredViews = registeredViews;

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkMeterProviderBuilder.java

@@ -15,7 +15,7 @@
 import io.opentelemetry.sdk.metrics.internal.MeterConfig;
 import io.opentelemetry.sdk.metrics.internal.SdkMeterProviderUtil;
 import io.opentelemetry.sdk.metrics.internal.debug.SourceInfo;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
+import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilterInternal;
 import io.opentelemetry.sdk.metrics.internal.view.RegisteredView;
 import io.opentelemetry.sdk.resources.Resource;
 import java.util.ArrayList;
@@ -36,15 +36,16 @@ public final class SdkMeterProviderBuilder {
    *
    * @see #setExemplarFilter(ExemplarFilter)
    */
-  private static final ExemplarFilter DEFAULT_EXEMPLAR_FILTER = ExemplarFilter.traceBased();
+  private static final ExemplarFilterInternal DEFAULT_EXEMPLAR_FILTER =
+      ExemplarFilterInternal.asExemplarFilterInternal(ExemplarFilter.traceBased());
 
   private Clock clock = Clock.getDefault();
   private Resource resource = Resource.getDefault();
   private final IdentityHashMap<MetricReader, CardinalityLimitSelector> metricReaders =
       new IdentityHashMap<>();
   private final List<MetricProducer> metricProducers = new ArrayList<>();
   private final List<RegisteredView> registeredViews = new ArrayList<>();
-  private ExemplarFilter exemplarFilter = DEFAULT_EXEMPLAR_FILTER;
+  private ExemplarFilterInternal exemplarFilter = DEFAULT_EXEMPLAR_FILTER;
   private ScopeConfiguratorBuilder<MeterConfig> meterConfiguratorBuilder =
       MeterConfig.configuratorBuilder();
 
@@ -80,14 +81,9 @@ public SdkMeterProviderBuilder addResource(Resource resource) {
     return this;
   }
 
-  /**
-   * Assign an {@link ExemplarFilter} for all metrics created by Meters.
-   *
-   * <p>This method is experimental so not public. You may reflectively call it using {@link
-   * SdkMeterProviderUtil#setExemplarFilter(SdkMeterProviderBuilder, ExemplarFilter)}.
-   */
-  SdkMeterProviderBuilder setExemplarFilter(ExemplarFilter filter) {
-    this.exemplarFilter = filter;
+  /** Set the {@link ExemplarFilter} used for all instruments from all meters. */
+  public SdkMeterProviderBuilder setExemplarFilter(ExemplarFilter filter) {
+    this.exemplarFilter = ExemplarFilterInternal.asExemplarFilterInternal(filter);
     return this;
   }
 

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/SdkMeterProviderUtil.java

@@ -10,7 +10,6 @@
 import io.opentelemetry.sdk.metrics.SdkMeterProvider;
 import io.opentelemetry.sdk.metrics.SdkMeterProviderBuilder;
 import io.opentelemetry.sdk.metrics.ViewBuilder;
-import io.opentelemetry.sdk.metrics.internal.exemplar.ExemplarFilter;
 import io.opentelemetry.sdk.metrics.internal.view.AttributesProcessor;
 import io.opentelemetry.sdk.metrics.internal.view.StringPredicates;
 import java.lang.reflect.InvocationTargetException;
@@ -29,26 +28,6 @@ public final class SdkMeterProviderUtil {
 
   private SdkMeterProviderUtil() {}
 
-  /**
-   * Reflectively assign the {@link ExemplarFilter} to the {@link SdkMeterProviderBuilder}.
-   *
-   * @param sdkMeterProviderBuilder the builder
-   */
-  public static SdkMeterProviderBuilder setExemplarFilter(
-      SdkMeterProviderBuilder sdkMeterProviderBuilder, ExemplarFilter exemplarFilter) {
-    try {
-      Method method =
-          SdkMeterProviderBuilder.class.getDeclaredMethod(
-              "setExemplarFilter", ExemplarFilter.class);
-      method.setAccessible(true);
-      method.invoke(sdkMeterProviderBuilder, exemplarFilter);
-    } catch (NoSuchMethodException | IllegalAccessException | InvocationTargetException e) {
-      throw new IllegalStateException(
-          "Error calling setExemplarFilter on SdkMeterProviderBuilder", e);
-    }
-    return sdkMeterProviderBuilder;
-  }
-
   /** Reflectively set the {@link ScopeConfigurator} to the {@link SdkMeterProvider}. */
   public static void setMeterConfigurator(
       SdkMeterProvider sdkMeterProvider, ScopeConfigurator<MeterConfig> scopeConfigurator) {