Add support to remove instruments

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleCounter.java

@@ -45,4 +45,23 @@ public interface DoubleCounter {
    * @param context The explicit context to associate with this measurement.
    */
   void add(double value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleGauge.java

@@ -39,4 +39,23 @@ public interface DoubleGauge {
    * @param context The explicit context to associate with this measurement.
    */
   void set(double value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleHistogram.java

@@ -46,4 +46,23 @@ public interface DoubleHistogram {
    * @param context The explicit context to associate with this measurement.
    */
   void record(double value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

api/all/src/main/java/io/opentelemetry/api/metrics/DoubleUpDownCounter.java

@@ -45,4 +45,23 @@ public interface DoubleUpDownCounter {
    * @param context The explicit context to associate with this measurement.
    */
   void add(double value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

api/all/src/main/java/io/opentelemetry/api/metrics/LongCounter.java

@@ -46,4 +46,23 @@ public interface LongCounter {
    * @param context The explicit context to associate with this measurement.
    */
   void add(long value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

api/all/src/main/java/io/opentelemetry/api/metrics/LongGauge.java

@@ -39,4 +39,23 @@ public interface LongGauge {
    * @param context The explicit context to associate with this measurement.
    */
   void set(long value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

api/all/src/main/java/io/opentelemetry/api/metrics/LongHistogram.java

@@ -46,4 +46,23 @@ public interface LongHistogram {
    * @param context The explicit context to associate with this measurement.
    */
   void record(long value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

api/all/src/main/java/io/opentelemetry/api/metrics/LongUpDownCounter.java

@@ -45,4 +45,23 @@ public interface LongUpDownCounter {
    * @param context The explicit context to associate with this measurement.
    */
   void add(long value, Attributes attributes, Context context);
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes) {
+    remove(attributes, Context.current());
+  }
+
+  /**
+   * Remove the instrument.
+   *
+   * @param attributes A set of attributes to identify the instrument.
+   * @param context The explicit context to associate with this measurement.
+   * @since 1.56.0
+   */
+  default void remove(Attributes attributes, Context context) {}
 }

docs/apidiffs/current_vs_latest/opentelemetry-api.txt

@@ -1,2 +1,33 @@
 Comparing source compatibility of opentelemetry-api-1.56.0-SNAPSHOT.jar against opentelemetry-api-1.55.0.jar
-No changes.
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.DoubleCounter  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.DoubleGauge  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.DoubleHistogram  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.DoubleUpDownCounter  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.LongCounter  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.LongGauge  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.LongHistogram  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)
+***  MODIFIED INTERFACE: PUBLIC ABSTRACT io.opentelemetry.api.metrics.LongUpDownCounter  (not serializable)
+	===  CLASS FILE FORMAT VERSION: 52.0 <- 52.0
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes)
+	+++  NEW METHOD: PUBLIC(+) void remove(io.opentelemetry.api.common.Attributes, io.opentelemetry.context.Context)

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

@@ -56,6 +56,11 @@ public void add(double increment) {
     add(increment, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkDoubleCounterBuilder implements DoubleCounterBuilder {
 
     final InstrumentBuilder builder;

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

@@ -43,6 +43,11 @@ public void set(double value) {
     set(value, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkDoubleGaugeBuilder implements DoubleGaugeBuilder {
     final InstrumentBuilder builder;
 

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

@@ -56,6 +56,11 @@ public void record(double value) {
     record(value, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkDoubleHistogramBuilder implements DoubleHistogramBuilder {
 
     final InstrumentBuilder builder;

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

@@ -43,6 +43,11 @@ public void add(double increment) {
     add(increment, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkDoubleUpDownCounterBuilder implements DoubleUpDownCounterBuilder {
 
     final InstrumentBuilder builder;

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

@@ -57,6 +57,11 @@ public void add(long increment) {
     add(increment, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkLongCounterBuilder implements LongCounterBuilder {
 
     final InstrumentBuilder builder;

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

@@ -42,6 +42,11 @@ public void set(long value) {
     set(value, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkLongGaugeBuilder implements LongGaugeBuilder {
 
     final InstrumentBuilder builder;

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

@@ -57,6 +57,11 @@ public void record(long value) {
     record(value, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkLongHistogramBuilder implements LongHistogramBuilder {
 
     final InstrumentBuilder builder;

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

@@ -43,6 +43,11 @@ public void add(long increment) {
     add(increment, Attributes.empty());
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    storage.remove(attributes, context);
+  }
+
   static class SdkLongUpDownCounterBuilder implements LongUpDownCounterBuilder {
 
     final InstrumentBuilder builder;

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

@@ -369,6 +369,13 @@ public void recordDouble(double value, Attributes attributes, Context context) {
       }
     }
 
+    @Override
+    public void remove(Attributes attributes, Context context) {
+      for (WriteableMetricStorage storage : storages) {
+        storage.remove(attributes, context);
+      }
+    }
+
     @Override
     public boolean isEnabled() {
       for (WriteableMetricStorage storage : storages) {

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/state/DefaultSynchronousMetricStorage.java

@@ -140,6 +140,19 @@ public void recordDouble(double value, Attributes attributes, Context context) {
     }
   }
 
+  @Override
+  public void remove(Attributes attributes, Context context) {
+    if (!enabled) {
+      return;
+    }
+    AggregatorHolder<T> aggregatorHolder = getHolderForRecord();
+    try {
+      aggregatorHolder.aggregatorHandles.remove(attributes);
+    } finally {
+      releaseHolderForRecord(aggregatorHolder);
+    }
+  }
+
   @Override
   public void setEnabled(boolean enabled) {
     this.enabled = enabled;

sdk/metrics/src/main/java/io/opentelemetry/sdk/metrics/internal/state/WriteableMetricStorage.java

@@ -23,6 +23,9 @@ public interface WriteableMetricStorage {
   /** Records a measurement. */
   void recordDouble(double value, Attributes attributes, Context context);
 
+  /** Remove a measurement. */
+  default void remove(Attributes attributes, Context context) {}
+
   /**
    * Returns {@code true} if the storage is actively recording measurements, and {@code false}
    * otherwise (i.e. noop / empty metric storage is installed).

sdk/metrics/src/test/java/io/opentelemetry/sdk/metrics/SdkDoubleCounterTest.java

@@ -58,6 +58,15 @@ void collectMetrics_NoRecords() {
     assertThat(sdkMeterReader.collectAllMetrics()).isEmpty();
   }
 
+  @Test
+  void collectMetrics_Remove() {
+    DoubleCounter counter = sdkMeter.counterBuilder("testCounter").ofDoubles().build();
+    Attributes attrs = Attributes.of(stringKey("key"), "value");
+    counter.add(1, attrs);
+    counter.remove(attrs);
+    assertThat(sdkMeterReader.collectAllMetrics()).isEmpty();
+  }
+
   @Test
   void collectMetrics_WithEmptyAttributes() {
     DoubleCounter doubleCounter =