Bound instruments

CHANGELOG.md

@@ -13,6 +13,8 @@ release.
 
 ### Metrics
 
+- Add in-development `Bind` API to synchronous instruments.
+  ([#5050](https://github.com/open-telemetry/opentelemetry-specification/pull/5050))
 - Stabilize sections of Prometheus Metrics Exporter.
   - Stabilize temporality.
     ([#5024](https://github.com/open-telemetry/opentelemetry-specification/issues/5024))

spec-compliance-matrix.md

@@ -130,6 +130,7 @@ formats is required. Implementing more than one format is optional.
 | Instrument descriptions conform to the specified syntax. |  | - | + |  | - | + | + |  |  | - | + |  | - |
 | Instrument supports the advisory ExplicitBucketBoundaries parameter. |  | + | + |  |  |  | + |  |  |  |  |  | - |
 | Instrument supports the advisory Attributes parameter. |  | - | + |  |  |  | + |  |  |  |  |  | - |
+| Synchronous instruments support Bind to pre-associate attributes. | X | - | - | - | - | - | - | - | - | - | - | - | - |
 | All methods of `MeterProvider` are safe to be called concurrently. |  | + | + | + | - |  | + |  |  | + | + |  | - |
 | All methods of `Meter` are safe to be called concurrently. |  | + | + | + | - |  | + |  |  | + | + |  | - |
 | All methods of any instrument are safe to be called concurrently. |  | + | + | + | - |  | + |  |  | + | + |  | - |

spec-compliance-matrix/cpp.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '+'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/dotnet.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '+'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/erlang.yaml

@@ -223,6 +223,8 @@ sections:
         status: '+'
       - name: Instrument supports the advisory Attributes parameter.
         status: '+'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '+'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/go.yaml

@@ -223,6 +223,8 @@ sections:
         status: '+'
       - name: Instrument supports the advisory Attributes parameter.
         status: '-'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '+'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/java.yaml

@@ -223,6 +223,8 @@ sections:
         status: '+'
       - name: Instrument supports the advisory Attributes parameter.
         status: '+'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '+'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/js.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '+'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/kotlin.yaml

@@ -223,6 +223,8 @@ sections:
         status: '-'
       - name: Instrument supports the advisory Attributes parameter.
         status: '-'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '-'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/php.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '?'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/python.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '-'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/ruby.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '?'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/rust.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '?'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/swift.yaml

@@ -223,6 +223,8 @@ sections:
         status: '?'
       - name: Instrument supports the advisory Attributes parameter.
         status: '?'
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        status: '-'
       - name: All methods of `MeterProvider` are safe to be called concurrently.
         status: '?'
       - name: All methods of `Meter` are safe to be called concurrently.

spec-compliance-matrix/template.yaml

@@ -157,6 +157,8 @@ sections:
       - name: Instrument descriptions conform to the specified syntax.
       - name: Instrument supports the advisory ExplicitBucketBoundaries parameter.
       - name: Instrument supports the advisory Attributes parameter.
+      - name: Synchronous instruments support Bind to pre-associate attributes.
+        optional: true
       - name: All methods of `MeterProvider` are safe to be called concurrently.
       - name: All methods of `Meter` are safe to be called concurrently.
       - name: All methods of any instrument are safe to be called concurrently.

specification/metrics/api.md

@@ -31,28 +31,33 @@ weight: 1
       - [Asynchronous Instrument API](#asynchronous-instrument-api)
   * [General operations](#general-operations)
     + [Enabled](#enabled)
+    + [Bind](#bind)
   * [Counter](#counter)
     + [Counter creation](#counter-creation)
     + [Counter operations](#counter-operations)
       - [Add](#add)
+      - [Bound Add](#bound-add)
   * [Asynchronous Counter](#asynchronous-counter)
     + [Asynchronous Counter creation](#asynchronous-counter-creation)
     + [Asynchronous Counter operations](#asynchronous-counter-operations)
   * [Histogram](#histogram)
     + [Histogram creation](#histogram-creation)
     + [Histogram operations](#histogram-operations)
       - [Record](#record)
+      - [Bound Record](#bound-record)
   * [Gauge](#gauge)
     + [Gauge creation](#gauge-creation)
     + [Gauge operations](#gauge-operations)
       - [Record](#record-1)
+      - [Bound Record](#bound-record-1)
   * [Asynchronous Gauge](#asynchronous-gauge)
     + [Asynchronous Gauge creation](#asynchronous-gauge-creation)
     + [Asynchronous Gauge operations](#asynchronous-gauge-operations)
   * [UpDownCounter](#updowncounter)
     + [UpDownCounter creation](#updowncounter-creation)
     + [UpDownCounter operations](#updowncounter-operations)
       - [Add](#add-1)
+      - [Bound Add](#bound-add-1)
   * [Asynchronous UpDownCounter](#asynchronous-updowncounter)
     + [Asynchronous UpDownCounter creation](#asynchronous-updowncounter-creation)
     + [Asynchronous UpDownCounter operations](#asynchronous-updowncounter-operations)
@@ -476,6 +481,10 @@ All [synchronous instruments](#synchronous-instrument-api) SHOULD provide functi
 
 * [Report if instrument is `Enabled`](#enabled)
 
+All [synchronous instruments](#synchronous-instrument-api) MAY provide:
+
+* (**Development**) [Bind to a set of attributes](#bind)
+
 #### Enabled
 
 To help users avoid performing computationally expensive operations when
@@ -494,6 +503,56 @@ The returned value is not always static, it can change over time. The API
 SHOULD be documented that instrumentation authors needs to call this API each
 time they record a measurement to ensure they have the most up-to-date response.
 
+#### Bind
+
+**Status**: [Development](../document-status.md)
+
+The `Bind` API associates a fixed set of [Attributes](../common/README.md#attribute) with every
+measurement recorded on the returned bound instrument. Because attributes are resolved at bind
+time rather than at each recording, implementations can avoid per-recording attribute processing
+and lookup overhead.
+
+This API MUST accept the following parameter:
+
+* [Attributes](../common/README.md#attribute) to associate with every measurement recorded on
+  the returned bound instrument.
+
+  Users can provide attributes to associate with the bound instrument, but it is up
+  to their discretion. Therefore, this API MUST be structured to accept a variable
+  number of attributes, including none.
+
+This API MUST return a language-idiomatic type representing the instrument bound to those
+attributes.
+
+The returned bound instrument MUST support the instrument's core recording operation without
+accepting [Attributes](../common/README.md#attribute) as a parameter. The instrument kind
+determines the recording operation on the bound instrument:
+
+* [Counter](#counter): [Bound Add](#bound-add)
+* [Histogram](#histogram): [Bound Record](#bound-record)
+* [Gauge](#gauge): [Bound Record](#bound-record-1)
+* [UpDownCounter](#updowncounter): [Bound Add](#bound-add-1)
+
+Measurements recorded on the bound instrument can be associated with the
+[Context](../context/README.md).
+
+Here are some examples that [OpenTelemetry API](../overview.md#api) authors might consider:
+
+```java
+// Java
+
+LongCounter rolls = meter.counterBuilder("dice.rolls")
+    .setDescription("The number of times each side of the die was rolled")
+    .setUnit("{roll}")
+    .build();
+
+var face1 = rolls.bind(Attributes.of(AttributeKey.longKey("roll.value"), 1L));
+var face6 = rolls.bind(Attributes.of(AttributeKey.longKey("roll.value"), 6L));
+
+face1.add(1);
+face6.add(1);
+```
+
 ### Counter
 
 `Counter` is a [synchronous Instrument](#synchronous-instrument-api) which supports
@@ -596,6 +655,14 @@ counterPowerUsed.Add(13.5, new PowerConsumption { customer = "Tom" });
 counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_green_energy", true));
 ```
 
+##### Bound Add
+
+**Status**: [Development](../document-status.md)
+
+The bound counterpart to [Add](#add), obtained via [Bind](#bind). All semantics are
+identical to [Add](#add) except [Attributes](../common/README.md#attribute) are not
+accepted as a parameter.
+
 ### Asynchronous Counter
 
 Asynchronous Counter is an [asynchronous Instrument](#asynchronous-instrument-api)
@@ -825,6 +892,14 @@ httpServerDuration.Record(50, ("http.request.method", "POST"), ("url.scheme", "h
 httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", scheme = "http" });
 ```
 
+##### Bound Record
+
+**Status**: [Development](../document-status.md)
+
+The bound counterpart to [Record](#record), obtained via [Bind](#bind). All semantics are
+identical to [Record](#record) except [Attributes](../common/README.md#attribute) are not
+accepted as a parameter.
+
 ### Gauge
 
 `Gauge` is a [synchronous Instrument](#synchronous-instrument-api) which can be
@@ -914,6 +989,14 @@ backgroundNoiseLevel.record(4.3, roomA);
 backgroundNoiseLevel.record(2.5, roomB);
 ```
 
+##### Bound Record
+
+**Status**: [Development](../document-status.md)
+
+The bound counterpart to [Record](#record-1), obtained via [Bind](#bind). All semantics are
+identical to [Record](#record-1) except [Attributes](../common/README.md#attribute) are not
+accepted as a parameter.
+
 ### Asynchronous Gauge
 
 Asynchronous Gauge is an [asynchronous Instrument](#asynchronous-instrument-api)
@@ -1155,6 +1238,14 @@ customersInStore.Add(1, ("account.type", "commercial"));
 customersInStore.Add(-1, new Account { Type = "residential" });
 ```
 
+##### Bound Add
+
+**Status**: [Development](../document-status.md)
+
+The bound counterpart to [Add](#add-1), obtained via [Bind](#bind). All semantics are
+identical to [Add](#add-1) except [Attributes](../common/README.md#attribute) are not
+accepted as a parameter.
+
 ### Asynchronous UpDownCounter
 
 Asynchronous UpDownCounter is an [asynchronous

specification/metrics/sdk.md

@@ -54,6 +54,7 @@ weight: 3
     + [Instrument advisory parameter: `ExplicitBucketBoundaries`](#instrument-advisory-parameter-explicitbucketboundaries)
     + [Instrument advisory parameter: `Attributes`](#instrument-advisory-parameter-attributes)
   * [Instrument enabled](#instrument-enabled)
+  * [Instrument bind](#instrument-bind)
 - [Attribute limits](#attribute-limits)
 - [Exemplar](#exemplar)
   * [ExemplarFilter](#exemplarfilter)
@@ -1041,6 +1042,18 @@ Note: If a user makes no configuration changes, `Enabled` returns `true` since b
 default `MeterConfig.enabled=true` and instruments use the default
 aggregation when no matching views match the instrument.
 
+### Instrument bind
+
+**Status**: [Development](../document-status.md)
+
+A bound instrument MUST behave identically to calling the equivalent unbound recording
+operation with the pre-bound [Attributes](../common/README.md#attribute) on each
+measurement.
+
+The SDK SHOULD optimize by pre-resolving the underlying aggregator state at bind time,
+such that subsequent recordings bypass per-recording attribute processing and map
+lookup.
+
 ## Attribute limits
 
 **Status**: [Stable](../document-status.md)