Add other bound instrument interfaces

Author: jack-berg

api/incubator/src/main/java/io/opentelemetry/api/incubator/metrics/BoundDoubleCounter.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.metrics;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.metrics.DoubleCounter;
+import io.opentelemetry.context.Context;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link DoubleCounter} bound to a fixed set of {@link Attributes}, obtained via {@link
+ * ExtendedDoubleCounter#bind(Attributes)}.
+ *
+ * <p>Binding resolves the underlying timeseries once, so subsequent {@link #add(double)} calls
+ * record directly without the per-recording attribute processing and map lookup that {@link
+ * DoubleCounter#add(double, Attributes)} performs. This is useful when the set of attribute
+ * combinations is known ahead of time and the same series is recorded to repeatedly.
+ */
+@ThreadSafe
+public interface BoundDoubleCounter {
+
+  /**
+   * Records a value against the bound attributes.
+   *
+   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
+   * measurement.
+   *
+   * @param value The increment amount. MUST be non-negative.
+   */
+  void add(double value);
+
+  /**
+   * Records a value against the bound attributes, with an explicit {@link Context}.
+   *
+   * @param value The increment amount. MUST be non-negative.
+   * @param context The explicit context to associate with this measurement.
+   */
+  void add(double value, Context context);
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/metrics/BoundDoubleGauge.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.metrics;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.metrics.DoubleGauge;
+import io.opentelemetry.context.Context;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link DoubleGauge} bound to a fixed set of {@link Attributes}, obtained via {@link
+ * ExtendedDoubleGauge#bind(Attributes)}.
+ *
+ * <p>Binding resolves the underlying timeseries once, so subsequent {@link #set(double)} calls
+ * record directly without the per-recording attribute processing and map lookup that {@link
+ * DoubleGauge#set(double, Attributes)} performs. This is useful when the set of attribute
+ * combinations is known ahead of time and the same series is recorded to repeatedly.
+ */
+@ThreadSafe
+public interface BoundDoubleGauge {
+
+  /**
+   * Records the gauge value against the bound attributes.
+   *
+   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
+   * measurement.
+   *
+   * @param value The current gauge value.
+   */
+  void set(double value);
+
+  /**
+   * Records the gauge value against the bound attributes, with an explicit {@link Context}.
+   *
+   * @param value The current gauge value.
+   * @param context The explicit context to associate with this measurement.
+   */
+  void set(double value, Context context);
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/metrics/BoundDoubleHistogram.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.metrics;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.metrics.DoubleHistogram;
+import io.opentelemetry.context.Context;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link DoubleHistogram} bound to a fixed set of {@link Attributes}, obtained via {@link
+ * ExtendedDoubleHistogram#bind(Attributes)}.
+ *
+ * <p>Binding resolves the underlying timeseries once, so subsequent {@link #record(double)} calls
+ * record directly without the per-recording attribute processing and map lookup that {@link
+ * DoubleHistogram#record(double, Attributes)} performs. This is useful when the set of attribute
+ * combinations is known ahead of time and the same series is recorded to repeatedly.
+ */
+@ThreadSafe
+public interface BoundDoubleHistogram {
+
+  /**
+   * Records a value against the bound attributes.
+   *
+   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
+   * measurement.
+   *
+   * @param value The amount of the measurement. MUST be non-negative.
+   */
+  void record(double value);
+
+  /**
+   * Records a value against the bound attributes, with an explicit {@link Context}.
+   *
+   * @param value The amount of the measurement. MUST be non-negative.
+   * @param context The explicit context to associate with this measurement.
+   */
+  void record(double value, Context context);
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/metrics/BoundDoubleUpDownCounter.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.metrics;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.metrics.DoubleUpDownCounter;
+import io.opentelemetry.context.Context;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link DoubleUpDownCounter} bound to a fixed set of {@link Attributes}, obtained via {@link
+ * ExtendedDoubleUpDownCounter#bind(Attributes)}.
+ *
+ * <p>Binding resolves the underlying timeseries once, so subsequent {@link #add(double)} calls
+ * record directly without the per-recording attribute processing and map lookup that {@link
+ * DoubleUpDownCounter#add(double, Attributes)} performs. This is useful when the set of attribute
+ * combinations is known ahead of time and the same series is recorded to repeatedly.
+ */
+@ThreadSafe
+public interface BoundDoubleUpDownCounter {
+
+  /**
+   * Records a value against the bound attributes.
+   *
+   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
+   * measurement.
+   *
+   * @param value The increment amount. May be positive, negative or zero.
+   */
+  void add(double value);
+
+  /**
+   * Records a value against the bound attributes, with an explicit {@link Context}.
+   *
+   * @param value The increment amount. May be positive, negative or zero.
+   * @param context The explicit context to associate with this measurement.
+   */
+  void add(double value, Context context);
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/metrics/BoundLongGauge.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.metrics;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.metrics.LongGauge;
+import io.opentelemetry.context.Context;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link LongGauge} bound to a fixed set of {@link Attributes}, obtained via {@link
+ * ExtendedLongGauge#bind(Attributes)}.
+ *
+ * <p>Binding resolves the underlying timeseries once, so subsequent {@link #set(long)} calls record
+ * directly without the per-recording attribute processing and map lookup that {@link
+ * LongGauge#set(long, Attributes)} performs. This is useful when the set of attribute combinations
+ * is known ahead of time and the same series is recorded to repeatedly.
+ */
+@ThreadSafe
+public interface BoundLongGauge {
+
+  /**
+   * Records the gauge value against the bound attributes.
+   *
+   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
+   * measurement.
+   *
+   * @param value The current gauge value.
+   */
+  void set(long value);
+
+  /**
+   * Records the gauge value against the bound attributes, with an explicit {@link Context}.
+   *
+   * @param value The current gauge value.
+   * @param context The explicit context to associate with this measurement.
+   */
+  void set(long value, Context context);
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/metrics/BoundLongHistogram.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.metrics;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.metrics.LongHistogram;
+import io.opentelemetry.context.Context;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link LongHistogram} bound to a fixed set of {@link Attributes}, obtained via {@link
+ * ExtendedLongHistogram#bind(Attributes)}.
+ *
+ * <p>Binding resolves the underlying timeseries once, so subsequent {@link #record(long)} calls
+ * record directly without the per-recording attribute processing and map lookup that {@link
+ * LongHistogram#record(long, Attributes)} performs. This is useful when the set of attribute
+ * combinations is known ahead of time and the same series is recorded to repeatedly.
+ */
+@ThreadSafe
+public interface BoundLongHistogram {
+
+  /**
+   * Records a value against the bound attributes.
+   *
+   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
+   * measurement.
+   *
+   * @param value The amount of the measurement. MUST be non-negative.
+   */
+  void record(long value);
+
+  /**
+   * Records a value against the bound attributes, with an explicit {@link Context}.
+   *
+   * @param value The amount of the measurement. MUST be non-negative.
+   * @param context The explicit context to associate with this measurement.
+   */
+  void record(long value, Context context);
+}

api/incubator/src/main/java/io/opentelemetry/api/incubator/metrics/BoundLongUpDownCounter.java

@@ -0,0 +1,42 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.api.incubator.metrics;
+
+import io.opentelemetry.api.common.Attributes;
+import io.opentelemetry.api.metrics.LongUpDownCounter;
+import io.opentelemetry.context.Context;
+import javax.annotation.concurrent.ThreadSafe;
+
+/**
+ * A {@link LongUpDownCounter} bound to a fixed set of {@link Attributes}, obtained via {@link
+ * ExtendedLongUpDownCounter#bind(Attributes)}.
+ *
+ * <p>Binding resolves the underlying timeseries once, so subsequent {@link #add(long)} calls record
+ * directly without the per-recording attribute processing and map lookup that {@link
+ * LongUpDownCounter#add(long, Attributes)} performs. This is useful when the set of attribute
+ * combinations is known ahead of time and the same series is recorded to repeatedly.
+ */
+@ThreadSafe
+public interface BoundLongUpDownCounter {
+
+  /**
+   * Records a value against the bound attributes.
+   *
+   * <p>Note: This may use {@code Context.current()} to pull the context associated with this
+   * measurement.
+   *
+   * @param value The increment amount. May be positive, negative or zero.
+   */
+  void add(long value);
+
+  /**
+   * Records a value against the bound attributes, with an explicit {@link Context}.
+   *
+   * @param value The increment amount. May be positive, negative or zero.
+   * @param context The explicit context to associate with this measurement.
+   */
+  void add(long value, Context context);
+}