6195: DelegatingMetricData.

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

@@ -1,2 +1,61 @@
 Comparing source compatibility of opentelemetry-sdk-metrics-1.49.0-SNAPSHOT.jar against opentelemetry-sdk-metrics-1.48.0.jar
-No changes.
++++  NEW CLASS: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.metrics.data.DelegatingMetricData  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW INTERFACE: io.opentelemetry.sdk.metrics.data.MetricData
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) boolean equals(java.lang.Object)
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.metrics.data.Data<?> getData()
+	+++  NEW METHOD: PUBLIC(+) java.lang.String getDescription()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.common.InstrumentationScopeInfo getInstrumentationScopeInfo()
+	+++  NEW METHOD: PUBLIC(+) java.lang.String getName()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.resources.Resource getResource()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.metrics.data.MetricDataType getType()
+	+++  NEW METHOD: PUBLIC(+) java.lang.String getUnit()
+	+++  NEW METHOD: PUBLIC(+) int hashCode()
+	+++  NEW METHOD: PUBLIC(+) java.lang.String toString()
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.DoubleExemplarData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.DoubleExemplarData create(io.opentelemetry.api.common.Attributes, long, io.opentelemetry.api.trace.SpanContext, double)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.DoublePointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.DoublePointData create(long, long, io.opentelemetry.api.common.Attributes, double)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets create(int, int, java.util.List<java.lang.Long>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ExponentialHistogramData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ExponentialHistogramData create(io.opentelemetry.sdk.metrics.data.AggregationTemporality, java.util.Collection<io.opentelemetry.sdk.metrics.data.ExponentialHistogramPointData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ExponentialHistogramPointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ExponentialHistogramPointData create(int, double, long, boolean, double, boolean, double, io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets, io.opentelemetry.sdk.metrics.data.ExponentialHistogramBuckets, long, long, io.opentelemetry.api.common.Attributes, java.util.List<io.opentelemetry.sdk.metrics.data.DoubleExemplarData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.GaugeData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	GENERIC TEMPLATES: === T:io.opentelemetry.sdk.metrics.data.PointData
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.GaugeData<T> create(java.util.Collection<T>)
+		GENERIC TEMPLATES: +++ T:io.opentelemetry.sdk.metrics.data.PointData
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.HistogramData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.HistogramData create(io.opentelemetry.sdk.metrics.data.AggregationTemporality, java.util.Collection<io.opentelemetry.sdk.metrics.data.HistogramPointData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.HistogramPointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.HistogramPointData create(long, long, io.opentelemetry.api.common.Attributes, double, boolean, double, boolean, double, java.util.List<java.lang.Double>, java.util.List<java.lang.Long>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.LongExemplarData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.LongExemplarData create(io.opentelemetry.api.common.Attributes, long, io.opentelemetry.api.trace.SpanContext, long)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.LongPointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.LongPointData create(long, long, io.opentelemetry.api.common.Attributes, long)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.SumData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	GENERIC TEMPLATES: === T:io.opentelemetry.sdk.metrics.data.PointData
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.internal.data.ImmutableSumData<T> create(boolean, io.opentelemetry.sdk.metrics.data.AggregationTemporality, java.util.Collection<T>)
+		GENERIC TEMPLATES: +++ T:io.opentelemetry.sdk.metrics.data.PointData
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.SummaryData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.SummaryData create(java.util.Collection<io.opentelemetry.sdk.metrics.data.SummaryPointData>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.SummaryPointData  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.SummaryPointData create(long, long, io.opentelemetry.api.common.Attributes, long, double, java.util.List<io.opentelemetry.sdk.metrics.data.ValueAtQuantile>)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.sdk.metrics.data.ValueAtQuantile  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.metrics.data.ValueAtQuantile create(double, double)

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

@@ -1,2 +1,18 @@
 Comparing source compatibility of opentelemetry-sdk-testing-1.49.0-SNAPSHOT.jar against opentelemetry-sdk-testing-1.48.0.jar
-No changes.
++++  NEW CLASS: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW CONSTRUCTOR: PUBLIC(+) TestMetricData()
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder builder()
++++  NEW CLASS: PUBLIC(+) ABSTRACT(+) STATIC(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW CONSTRUCTOR: PUBLIC(+) TestMetricData$Builder()
+	+++  NEW METHOD: PUBLIC(+) io.opentelemetry.sdk.testing.metrics.TestMetricData build()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder setData(io.opentelemetry.sdk.metrics.data.Data<?>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder setDescription(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder setInstrumentationScopeInfo(io.opentelemetry.sdk.common.InstrumentationScopeInfo)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder setName(java.lang.String)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder setResource(io.opentelemetry.sdk.resources.Resource)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder setType(io.opentelemetry.sdk.metrics.data.MetricDataType)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.sdk.testing.metrics.TestMetricData$Builder setUnit(java.lang.String)

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/DelegatingMetricData.java

@@ -0,0 +1,188 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.sdk.metrics.data;
+
+import static java.util.Objects.requireNonNull;
+
+import io.opentelemetry.sdk.common.InstrumentationScopeInfo;
+import io.opentelemetry.sdk.resources.Resource;
+
+/**
+ * A {@link MetricData} which delegates all methods to another {@link MetricData}. Extend this class
+ * to modify the {@link MetricData} that will be exported, for example by creating a delegating
+ * {@link io.opentelemetry.sdk.metrics.export.MetricExporter} which wraps {@link MetricData} with a
+ * custom implementation.
+ *
+ * <p>Example usage:
+ *
+ * <pre>{@code
+ * // class MetricDataWithCustomDescription extends DelegatingMetricData {
+ * //
+ * //   private final String description;
+ * //
+ * //   MetricDataWithCustomDescription(MetricData delegate) {
+ * //     super(delegate);
+ * //     this.description = delegate.getDescription() + " (custom)";
+ * //   }
+ * //
+ * //   @Override
+ * //   public String getDescription() {
+ * //     return description;
+ * //   }
+ * // }
+ * }</pre>
+ *
+ */
+public abstract class DelegatingMetricData implements MetricData {
+
+  private final MetricData delegate;
+
+  protected DelegatingMetricData(MetricData delegate) {
+    this.delegate = requireNonNull(delegate, "delegate");
+  }
+
+  /**
+   * Returns the resource associated with this metric data.
+   *
+   * @return the {@link Resource} instance.
+   */
+  @Override
+  public Resource getResource() {
+    return delegate.getResource();
+  }
+
+  /**
+   * Returns the instrumentation library information associated with this metric data.
+   *
+   * @return the {@link InstrumentationScopeInfo} instance.
+   */
+  @Override
+  public InstrumentationScopeInfo getInstrumentationScopeInfo() {
+    return delegate.getInstrumentationScopeInfo();
+  }
+
+  /**
+   * Returns the name of the metric.
+   *
+   * @return the name of the metric.
+   */
+  @Override
+  public String getName() {
+    return delegate.getName();
+  }
+
+  /**
+   * Returns the description of the metric.
+   *
+   * @return the description of the metric.
+   */
+  @Override
+  public String getDescription() {
+    return delegate.getDescription();
+  }
+
+  /**
+   * Returns the unit of the metric.
+   *
+   * @return the unit of the metric.
+   */
+  @Override
+  public String getUnit() {
+    return delegate.getUnit();
+  }
+
+  /**
+   * Returns the type of the metric.
+   *
+   * @return the type of the metric.
+   */
+  @Override
+  public MetricDataType getType() {
+    return delegate.getType();
+  }
+
+  /**
+   * Returns the data of the metric.
+   *
+   * @return the data of the metric.
+   */
+  @Override
+  public Data<?> getData() {
+    return delegate.getData();
+  }
+
+  /**
+   * Returns a boolean indicating whether the delegate {@link MetricData} is equal to this {@code
+   * MetricData}.
+   *
+   * @param o the object to compare to.
+   * @return a boolean indicating whether the delegate {@link MetricData} is equal to this {@code
+   *     MetricData}.
+   */
+  @Override
+  public boolean equals(Object o) {
+    if (o == this) {
+      return true;
+    }
+    if (o instanceof MetricData) {
+      MetricData that = (MetricData) o;
+      return getResource().equals(that.getResource())
+          && getInstrumentationScopeInfo().equals(that.getInstrumentationScopeInfo())
+          && getName().equals(that.getName())
+          && getDescription().equals(that.getDescription())
+          && getUnit().equals(that.getUnit())
+          && getType().equals(that.getType())
+          && getData().equals(that.getData());
+    }
+    return false;
+  }
+
+  /**
+   * Returns a hash code value for the delegate {@link MetricData}.
+   *
+   * @return a hash code value for the delegate {@link MetricData}.
+   */
+  @Override
+  public int hashCode() {
+    int code = 1;
+    code *= 1000003;
+    code ^= getResource().hashCode();
+    code *= 1000003;
+    code ^= getInstrumentationScopeInfo().hashCode();
+    code *= 1000003;
+    code ^= getName().hashCode();
+    code *= 1000003;
+    code ^= getDescription().hashCode();
+    code *= 1000003;
+    code ^= getUnit().hashCode();
+    code *= 1000003;
+    code ^= getType().hashCode();
+    code *= 1000003;
+    code ^= getData().hashCode();
+    return code;
+  }
+
+  /** Returns a string representation of the delegate {@link MetricData}. */
+  @Override
+  public String toString() {
+    return "DelegatingMetricData{"
+        + "resource="
+        + getResource()
+        + ", instrumentationScopeInfo="
+        + getInstrumentationScopeInfo()
+        + ", name="
+        + getName()
+        + ", description="
+        + getDescription()
+        + ", unit="
+        + getUnit()
+        + ", type="
+        + getType()
+        + ", data="
+        + getData()
+        + "}";
+  }
+}

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/DoubleExemplarData.java

@@ -5,6 +5,9 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.trace.SpanContext;
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableDoubleExemplarData;
 import javax.annotation.concurrent.Immutable;
 
 /**
@@ -14,6 +17,22 @@
  */
 @Immutable
 public interface DoubleExemplarData extends ExemplarData {
+
+  /**
+   * Construct a new exemplar.
+   *
+   * @param filteredAttributes The set of {@link Attributes} not already associated with the {@link
+   *     PointData}.
+   * @param recordTimeNanos The time when the sample qas recorded in nanoseconds.
+   * @param spanContext The associated span context.
+   * @param value The value recorded.
+   */
+  static DoubleExemplarData create(
+      Attributes filteredAttributes, long recordTimeNanos, SpanContext spanContext, double value) {
+    return ImmutableDoubleExemplarData.create(
+        filteredAttributes, recordTimeNanos, spanContext, value);
+  }
+
   /** Numerical value of the measurement that was recorded. */
   double getValue();
 }

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/DoublePointData.java

@@ -5,6 +5,9 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableDoublePointData;
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -13,6 +16,23 @@
  * @since 1.14.0
  */
 public interface DoublePointData extends PointData {
+
+  /**
+   * Creates a {@link DoublePointData}.
+   *
+   * @param startEpochNanos The starting time for the period where this point was sampled. Note:
+   *     While start time is optional in OTLP, all SDKs should produce it for all their metrics, so
+   *     it is required here.
+   * @param epochNanos The ending time for the period when this value was sampled.
+   * @param attributes The set of attributes associated with this point.
+   * @param value The value that was sampled.
+   */
+  static DoublePointData create(
+      long startEpochNanos, long epochNanos, Attributes attributes, double value) {
+    return ImmutableDoublePointData.create(
+        startEpochNanos, epochNanos, attributes, value, Collections.emptyList());
+  }
+
   /** Returns the value of the data point. */
   double getValue();
 

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramBuckets.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableExponentialHistogramBuckets;
 import java.util.List;
 import javax.annotation.concurrent.Immutable;
 
@@ -25,6 +26,16 @@
 @Immutable
 public interface ExponentialHistogramBuckets {
 
+  /**
+   * Create a ExponentialHistogramBuckets.
+   *
+   * @return a ExponentialHistogramBuckets.
+   */
+  @SuppressWarnings("TooManyParameters")
+  static ExponentialHistogramBuckets create(int scale, int offset, List<Long> bucketCounts) {
+    return ImmutableExponentialHistogramBuckets.create(scale, offset, bucketCounts);
+  }
+
   /** The scale of the buckets. Must align with {@link ExponentialHistogramPointData#getScale()}. */
   int getScale();
 

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/data/ExponentialHistogramData.java

@@ -5,6 +5,7 @@
 
 package io.opentelemetry.sdk.metrics.data;
 
+import io.opentelemetry.sdk.metrics.internal.data.ImmutableExponentialHistogramData;
 import java.util.Collection;
 import javax.annotation.concurrent.Immutable;
 
@@ -24,6 +25,12 @@
 @Immutable
 public interface ExponentialHistogramData extends Data<ExponentialHistogramPointData> {
 
+  /** Returns a new {@link ExponentialHistogramData}. */
+  static ExponentialHistogramData create(
+      AggregationTemporality temporality, Collection<ExponentialHistogramPointData> points) {
+    return ImmutableExponentialHistogramData.create(temporality, points);
+  }
+
   /**
    * Returns the {@code AggregationTemporality} of this metric.
    *