Add attributes advice API (just DoubleCounter for now) (#5677)

open-telemetry · Aug 16, 2023 · 35b41ab · 35b41ab
1 parent ff79bb7
commit 35b41ab
Show file tree

Hide file tree

Showing 18 changed files with 485 additions and 61 deletions.
diff --git a/...r/src/main/java/io/opentelemetry/extension/incubator/metrics/CounterAdviceConfigurer.java b/...r/src/main/java/io/opentelemetry/extension/incubator/metrics/CounterAdviceConfigurer.java
@@ -0,0 +1,17 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.extension.incubator.metrics;
+
+import io.opentelemetry.api.common.AttributeKey;
+import io.opentelemetry.api.metrics.DoubleCounter;
+import java.util.List;
+
+/** Configure advice for implementation of {@link DoubleCounter}. */
+public interface CounterAdviceConfigurer {
+
+  /** Specify the recommended set of attribute keys to be used for this counter. */
+  CounterAdviceConfigurer setAttributes(List<AttributeKey<?>> attributes);
+}
diff --git a/.../main/java/io/opentelemetry/extension/incubator/metrics/ExtendedDoubleCounterBuilder.java b/.../main/java/io/opentelemetry/extension/incubator/metrics/ExtendedDoubleCounterBuilder.java
@@ -0,0 +1,18 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.extension.incubator.metrics;
+
+import io.opentelemetry.api.metrics.DoubleCounterBuilder;
+import java.util.function.Consumer;
+
+/** Extended {@link DoubleCounterBuilder} with experimental APIs. */
+public interface ExtendedDoubleCounterBuilder extends DoubleCounterBuilder {
+
+  /** Specify advice for counter implementations. */
+  default DoubleCounterBuilder setAdvice(Consumer<CounterAdviceConfigurer> adviceConsumer) {
+    return this;
+  }
+}
diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/AbstractInstrumentBuilder.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/AbstractInstrumentBuilder.java
@@ -28,10 +28,10 @@ abstract class AbstractInstrumentBuilder<BuilderT extends AbstractInstrumentBuil
   private final InstrumentValueType valueType;
   private String description;
   private String unit;
-  private Advice advice;
 
   protected final MeterSharedState meterSharedState;
   protected final String instrumentName;
+  protected final Advice.AdviceBuilder adviceBuilder;
 
   AbstractInstrumentBuilder(
       MeterProviderSharedState meterProviderSharedState,
@@ -49,7 +49,7 @@ abstract class AbstractInstrumentBuilder<BuilderT extends AbstractInstrumentBuil
         name,
         description,
         unit,
-        Advice.empty());
+        Advice.builder());
   }
 
   AbstractInstrumentBuilder(
@@ -60,15 +60,15 @@ abstract class AbstractInstrumentBuilder<BuilderT extends AbstractInstrumentBuil
       String name,
       String description,
       String unit,
-      Advice advice) {
+      Advice.AdviceBuilder adviceBuilder) {
     this.type = type;
     this.valueType = valueType;
     this.instrumentName = name;
     this.description = description;
     this.unit = unit;
     this.meterProviderSharedState = meterProviderSharedState;
     this.meterSharedState = meterSharedState;
-    this.advice = advice;
+    this.adviceBuilder = adviceBuilder;
   }
 
   protected abstract BuilderT getThis();
@@ -85,17 +85,19 @@ public BuilderT setDescription(String description) {
 
   protected <T> T swapBuilder(SwapBuilder<T> swapper) {
     return swapper.newBuilder(
-        meterProviderSharedState, meterSharedState, instrumentName, description, unit, advice);
-  }
-
-  protected void setAdvice(Advice advice) {
-    this.advice = advice;
+        meterProviderSharedState,
+        meterSharedState,
+        instrumentName,
+        description,
+        unit,
+        adviceBuilder);
   }
 
   final <I extends AbstractInstrument> I buildSynchronousInstrument(
       BiFunction<InstrumentDescriptor, WriteableMetricStorage, I> instrumentFactory) {
     InstrumentDescriptor descriptor =
-        InstrumentDescriptor.create(instrumentName, description, unit, type, valueType, advice);
+        InstrumentDescriptor.create(
+            instrumentName, description, unit, type, valueType, adviceBuilder.build());
     WriteableMetricStorage storage =
         meterSharedState.registerSynchronousMetricStorage(descriptor, meterProviderSharedState);
     return instrumentFactory.apply(descriptor, storage);
@@ -123,15 +125,17 @@ final SdkObservableInstrument registerLongAsynchronousInstrument(
 
   final SdkObservableMeasurement buildObservableMeasurement(InstrumentType type) {
     InstrumentDescriptor descriptor =
-        InstrumentDescriptor.create(instrumentName, description, unit, type, valueType, advice);
+        InstrumentDescriptor.create(
+            instrumentName, description, unit, type, valueType, adviceBuilder.build());
     return meterSharedState.registerObservableMeasurement(descriptor);
   }
 
   @Override
   public String toString() {
     return this.getClass().getSimpleName()
         + "{descriptor="
-        + InstrumentDescriptor.create(instrumentName, description, unit, type, valueType, advice)
+        + InstrumentDescriptor.create(
+            instrumentName, description, unit, type, valueType, adviceBuilder.build())
         + "}";
   }
 
@@ -143,6 +147,6 @@ T newBuilder(
         String name,
         String description,
         String unit,
-        Advice advice);
+        Advice.AdviceBuilder adviceBuilder);
   }
 }
diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkDoubleCounter.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkDoubleCounter.java
@@ -5,18 +5,22 @@
 
 package io.opentelemetry.sdk.metrics;
 
+import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.metrics.DoubleCounter;
 import io.opentelemetry.api.metrics.DoubleCounterBuilder;
 import io.opentelemetry.api.metrics.ObservableDoubleCounter;
 import io.opentelemetry.api.metrics.ObservableDoubleMeasurement;
 import io.opentelemetry.context.Context;
+import io.opentelemetry.extension.incubator.metrics.CounterAdviceConfigurer;
+import io.opentelemetry.extension.incubator.metrics.ExtendedDoubleCounterBuilder;
 import io.opentelemetry.sdk.internal.ThrottlingLogger;
 import io.opentelemetry.sdk.metrics.internal.descriptor.Advice;
 import io.opentelemetry.sdk.metrics.internal.descriptor.InstrumentDescriptor;
 import io.opentelemetry.sdk.metrics.internal.state.MeterProviderSharedState;
 import io.opentelemetry.sdk.metrics.internal.state.MeterSharedState;
 import io.opentelemetry.sdk.metrics.internal.state.WriteableMetricStorage;
+import java.util.List;
 import java.util.function.Consumer;
 import java.util.logging.Level;
 import java.util.logging.Logger;
@@ -56,15 +60,16 @@ public void add(double increment) {
   }
 
   static final class SdkDoubleCounterBuilder
-      extends AbstractInstrumentBuilder<SdkDoubleCounterBuilder> implements DoubleCounterBuilder {
+      extends AbstractInstrumentBuilder<SdkDoubleCounterBuilder>
+      implements ExtendedDoubleCounterBuilder, CounterAdviceConfigurer {
 
     SdkDoubleCounterBuilder(
         MeterProviderSharedState meterProviderSharedState,
         MeterSharedState sharedState,
         String name,
         String description,
         String unit,
-        Advice advice) {
+        Advice.AdviceBuilder adviceBuilder) {
       super(
           meterProviderSharedState,
           sharedState,
@@ -73,14 +78,20 @@ static final class SdkDoubleCounterBuilder
           name,
           description,
           unit,
-          advice);
+          adviceBuilder);
     }
 
     @Override
     protected SdkDoubleCounterBuilder getThis() {
       return this;
     }
 
+    @Override
+    public DoubleCounterBuilder setAdvice(Consumer<CounterAdviceConfigurer> adviceConsumer) {
+      adviceConsumer.accept(this);
+      return this;
+    }
+
     @Override
     public SdkDoubleCounter build() {
       return buildSynchronousInstrument(SdkDoubleCounter::new);
@@ -96,5 +107,11 @@ public ObservableDoubleCounter buildWithCallback(
     public ObservableDoubleMeasurement buildObserver() {
       return buildObservableMeasurement(InstrumentType.OBSERVABLE_COUNTER);
     }
+
+    @Override
+    public CounterAdviceConfigurer setAttributes(List<AttributeKey<?>> attributes) {
+      adviceBuilder.setAttributes(attributes);
+      return this;
+    }
   }
 }
diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkDoubleHistogram.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkDoubleHistogram.java
@@ -12,7 +12,6 @@
 import io.opentelemetry.extension.incubator.metrics.DoubleHistogramAdviceConfigurer;
 import io.opentelemetry.extension.incubator.metrics.ExtendedDoubleHistogramBuilder;
 import io.opentelemetry.sdk.internal.ThrottlingLogger;
-import io.opentelemetry.sdk.metrics.internal.descriptor.Advice;
 import io.opentelemetry.sdk.metrics.internal.descriptor.InstrumentDescriptor;
 import io.opentelemetry.sdk.metrics.internal.state.MeterProviderSharedState;
 import io.opentelemetry.sdk.metrics.internal.state.MeterSharedState;
@@ -99,7 +98,7 @@ public LongHistogramBuilder ofLongs() {
     @Override
     public DoubleHistogramAdviceConfigurer setExplicitBucketBoundaries(
         List<Double> bucketBoundaries) {
-      setAdvice(Advice.create(bucketBoundaries));
+      adviceBuilder.setExplicitBucketBoundaries(bucketBoundaries);
       return this;
     }
   }

diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkDoubleUpDownCounter.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkDoubleUpDownCounter.java
@@ -52,7 +52,7 @@ static final class SdkDoubleUpDownCounterBuilder
         String name,
         String description,
         String unit,
-        Advice advice) {
+        Advice.AdviceBuilder adviceBuilder) {
       super(
           meterProviderSharedState,
           sharedState,
@@ -61,7 +61,7 @@ static final class SdkDoubleUpDownCounterBuilder
           name,
           description,
           unit,
-          advice);
+          adviceBuilder);
     }
 
     @Override

diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkLongGaugeBuilder.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkLongGaugeBuilder.java
@@ -22,7 +22,7 @@ final class SdkLongGaugeBuilder extends AbstractInstrumentBuilder<SdkLongGaugeBu
       String name,
       String description,
       String unit,
-      Advice advice) {
+      Advice.AdviceBuilder adviceBuilder) {
     super(
         meterProviderSharedState,
         sharedState,
@@ -31,7 +31,7 @@ final class SdkLongGaugeBuilder extends AbstractInstrumentBuilder<SdkLongGaugeBu
         name,
         description,
         unit,
-        advice);
+        adviceBuilder);
   }
 
   @Override

diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkLongHistogram.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/SdkLongHistogram.java
@@ -66,7 +66,7 @@ static final class SdkLongHistogramBuilder
         String name,
         String description,
         String unit,
-        Advice advice) {
+        Advice.AdviceBuilder adviceBuilder) {
       super(
           meterProviderSharedState,
           sharedState,
@@ -75,7 +75,7 @@ static final class SdkLongHistogramBuilder
           name,
           description,
           unit,
-          advice);
+          adviceBuilder);
     }
 
     @Override
@@ -99,7 +99,7 @@ public SdkLongHistogram build() {
     public LongHistogramAdviceConfigurer setExplicitBucketBoundaries(List<Long> bucketBoundaries) {
       List<Double> doubleBoundaries =
           bucketBoundaries.stream().map(Long::doubleValue).collect(Collectors.toList());
-      setAdvice(Advice.create(doubleBoundaries));
+      adviceBuilder.setExplicitBucketBoundaries(doubleBoundaries);
       return this;
     }
   }

diff --git a/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/descriptor/Advice.java b/sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/descriptor/Advice.java
@@ -6,6 +6,7 @@
 package io.opentelemetry.sdk.metrics.internal.descriptor;
 
 import com.google.auto.value.AutoValue;
+import io.opentelemetry.api.common.AttributeKey;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
@@ -16,28 +17,64 @@
 @Immutable
 public abstract class Advice {
 
-  private static final Advice EMPTY_ADVICE = create(null);
+  private static final Advice EMPTY_ADVICE = builder().build();
 
   public static Advice empty() {
     return EMPTY_ADVICE;
   }
 
-  /**
-   * Creates a new {@link Advice} with the given explicit bucket histogram boundaries.
-   *
-   * @param explicitBucketBoundaries the explicit bucket histogram boundaries.
-   * @return a new {@link Advice} with the given bucket boundaries.
-   */
-  public static Advice create(@Nullable List<Double> explicitBucketBoundaries) {
-    if (explicitBucketBoundaries != null) {
-      explicitBucketBoundaries =
-          Collections.unmodifiableList(new ArrayList<>(explicitBucketBoundaries));
-    }
-    return new AutoValue_Advice(explicitBucketBoundaries);
+  public static AdviceBuilder builder() {
+    return new AutoValue_Advice.Builder();
   }
 
   Advice() {}
 
   @Nullable
   public abstract List<Double> getExplicitBucketBoundaries();
+
+  @Nullable
+  public abstract List<AttributeKey<?>> getAttributes();
+
+  public boolean hasAttributes() {
+    return getAttributes() != null;
+  }
+
+  @AutoValue.Builder
+  public abstract static class AdviceBuilder {
+
+    AdviceBuilder() {}
+
+    abstract AdviceBuilder explicitBucketBoundaries(
+        @Nullable List<Double> explicitBucketBoundaries);
+
+    /**
+     * Sets the explicit bucket histogram boundaries.
+     *
+     * @param explicitBucketBoundaries the explicit bucket histogram boundaries.
+     */
+    public AdviceBuilder setExplicitBucketBoundaries(
+        @Nullable List<Double> explicitBucketBoundaries) {
+      if (explicitBucketBoundaries != null) {
+        explicitBucketBoundaries =
+            Collections.unmodifiableList(new ArrayList<>(explicitBucketBoundaries));
+      }
+      return explicitBucketBoundaries(explicitBucketBoundaries);
+    }
+
+    abstract AdviceBuilder attributes(@Nullable List<AttributeKey<?>> attributes);
+
+    /**
+     * Sets the list of the attribute keys to be used for the resulting instrument.
+     *
+     * @param attributes the list of the attribute keys.
+     */
+    public AdviceBuilder setAttributes(@Nullable List<AttributeKey<?>> attributes) {
+      if (attributes != null) {
+        attributes = Collections.unmodifiableList(new ArrayList<>(attributes));
+      }
+      return attributes(attributes);
+    }
+
+    public abstract Advice build();
+  }
 }