Add synchronous gauge instrument, clarify temporality selection influ…

…ence on metric point persistence (#3540) Resolves #2318. Extends the metrics API to include a new synchronous gauge instrument, whose value can be set as measurements occur. This is useful when the measurements are made accessible via subscription, such as JFR events. There are interesting questions around the behavior of `start_time_unix_nano` and whether or not sync gauges continue to export series without new measurements. This PR has gone through some iteration (available to see via commit history), but as it currently stands, I've made the following changes: - Add new language stating that metric reader's configurable aggregation temporality as a function of instrument type influences the persistence of metric points across successive collections, as described in this #3540 (comment). This influence occurs regardless of whether the resulting metric point has an aggregation temporality field. In other words, sync gauge persistence behavior is influenced by aggregation temporality selection. - Add new language stating that metric reader's configurable aggregation temporality as a function of instrument type influences the starting timestamp of metric points. When an instrument is cumulative, its starting timestamp will always be the same. When an instrument is delta, its starting timestamp advances with successive collections. This influence occurs regardless of whether the resulting metric point has an aggregation temporality field. In other words, sync gauge starting timestamp is influenced by aggregation temporality selection. --------- Co-authored-by: Reiley Yang <[email protected]>
open-telemetry · Aug 16, 2023 · d4b241f · d4b241f
1 parent f20566d
commit d4b241f
Show file tree

Hide file tree

Showing 3 changed files with 137 additions and 7 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -66,6 +66,9 @@ release.
   ([#3613](https://github.com/open-telemetry/opentelemetry-specification/pull/3613))
 - Refine `MetricProvider.ForceFlush` and define `ForceFlush` for periodic exporting MetricReader.
   ([#3563](https://github.com/open-telemetry/opentelemetry-specification/pull/3563))
+- Add synchronous gauge instrument, clarify temporality selection influence on
+  metric point persistence.
+  ([#3540](https://github.com/open-telemetry/opentelemetry-specification/pull/3540))
 
 ### Logs
 

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -37,6 +37,10 @@ linkTitle: API
     + [Histogram creation](#histogram-creation)
     + [Histogram operations](#histogram-operations)
       - [Record](#record)
+  * [Gauge](#gauge)
+    + [Gauge creation](#gauge-creation)
+    + [Gauge operations](#gauge-operations)
+      - [Record](#record-1)
   * [Asynchronous Gauge](#asynchronous-gauge)
     + [Asynchronous Gauge creation](#asynchronous-gauge-creation)
     + [Asynchronous Gauge operations](#asynchronous-gauge-operations)
@@ -774,6 +778,97 @@ httpServerDuration.Record(50, ("http.request.method", "POST"), ("url.scheme", "h
 httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", scheme = "http" });
 ```
 
+### Gauge
+
+**Status**: [Experimental](../document-status.md)
+
+`Gauge` is a [synchronous Instrument](#synchronous-instrument-api) which can be
+used to record non-additive value(s) (e.g. the background noise level - it makes
+no sense to record the background noise level value from multiple rooms and sum
+them up) when changes occur.
+
+Note: If the values are additive (e.g. the process heap size - it makes sense to
+report the heap size from multiple processes and sum them up, so we get the
+total heap usage), use [UpDownCounter](#asynchronous-updowncounter).
+
+Note: Synchronous Gauge is normally used when the measurements are exposed via a
+subscription to change events (
+i.e. `backgroundNoiseLevel.onChange(value -> gauge.record(value))`). If the
+measurement is exposed via an accessor,
+use [Asynchronous Gauge](#asynchronous-gauge) to invoke the accessor in a
+callback function (
+i.e. `createObservableGauge(observable -> observable.record(backgroundNoiseLevel.getCurrentValue()))`.
+
+Example uses for Gauge:
+
+* subscribe to change events for the background noise level
+* subscribe to change events for the CPU fan speed
+
+#### Gauge creation
+
+There MUST NOT be any API for creating a `Gauge` other than with a
+[`Meter`](#meter). This MAY be called `CreateGauge`. If strong type is
+desired, [OpenTelemetry API](../overview.md#api) authors MAY decide the language
+idiomatic name(s), for example `CreateUInt64Gauge`, `CreateDoubleGauge`,
+`CreateGauge<UInt64>`, `CreateGauge<double>`.
+
+See the [general requirements for synchronous instruments](#synchronous-instrument-api).
+
+Here are some examples that [OpenTelemetry API](../overview.md#api) authors
+might consider:
+
+```java
+// Java
+
+DoubleGauge backgroundNoiseLevel = meter.gaugeBuilder("facility.noise.level")
+    .setDescription("Background noise level of rooms")
+    .setUnit("B")
+    .build();
+```
+
+#### Gauge operations
+
+##### Record
+
+Record the Gauge current value.
+
+This API SHOULD NOT return a value (it MAY return a dummy value if required by
+certain programming languages or systems, for example `null`, `undefined`).
+
+This API MUST accept the following parameter:
+
+* A numeric value. The current absolute value.
+
+  The value needs to be provided by a user. If possible, this API
+  SHOULD be structured so a user is obligated to provide this parameter. If it
+  is not possible to structurally enforce this obligation, this API MUST be
+  documented in a way to communicate to users that this parameter is needed.
+* [Attributes](../common/README.md#attribute) to associate with the value.
+
+  Users can provide attributes to associate with the value, but it is
+  up to their discretion. Therefore, this API MUST be structured to accept a
+  variable number of attributes, including none.
+
+The [OpenTelemetry API](../overview.md#api) authors MAY decide to allow flexible
+[attributes](../common/README.md#attribute) to be passed in as arguments. If
+the attribute names and types are provided during the [gauge
+creation](#gauge-creation), the [OpenTelemetry API](../overview.md#api)
+authors MAY allow attribute values to be passed in using a more efficient way
+(e.g. strong typed struct allocated on the callstack, tuple). The API MUST allow
+callers to provide flexible attributes at invocation time rather than having to
+register all the possible attribute names during the instrument creation. Here
+are some examples that [OpenTelemetry API](../overview.md#api) authors might
+consider:
+
+```java
+// Java
+Attributes roomA = Attributes.builder().put("room.id", "Rack A");
+Attributes roomB = Attributes.builder().put("room.id", "Rack B");
+
+backgroundNoiseLevel.record(4.3, roomA);
+backgroundNoiseLevel.record(2.5, roomB);
+```
+
 ### Asynchronous Gauge
 
 Asynchronous Gauge is an [asynchronous Instrument](#asynchronous-instrument-api)

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -527,6 +527,7 @@ an aggregation and `advice` to influence aggregation configuration parameters
 | [Asynchronous Counter](./api.md#asynchronous-counter)             | [Sum Aggregation](./sdk.md#sum-aggregation)                                                                                                                                    |
 | [UpDownCounter](./api.md#updowncounter)                           | [Sum Aggregation](./sdk.md#sum-aggregation)                                                                                                                                    |
 | [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation)                                                                                                                                    |
+| [Gauge](./api.md#gauge)                                           | [Last Value Aggregation](./sdk.md#last-value-aggregation)                                                                                                                      |
 | [Asynchronous Gauge](./api.md#asynchronous-gauge)                 | [Last Value Aggregation](./sdk.md#last-value-aggregation)                                                                                                                      |
 | [Histogram](./api.md#histogram)                                   | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation), with `ExplicitBucketBoundaries` from [advice](./api.md#instrument-advice) if provided |
 
@@ -703,7 +704,8 @@ given instrument before starting a subsequent round of collection.
 
 The implementation SHOULD NOT produce aggregated metric data for a
 previously-observed attribute set which is not observed during a successful
-callback.
+callback. See [MetricReader](#metricreader) for more details on the persistence
+of metrics across successive collections.
 
 ### Cardinality limits
 
@@ -1081,18 +1083,48 @@ typically with push-based metrics collection.
 
 The `MetricReader` MUST ensure that data points from OpenTelemetry
 [instruments](./api.md#instrument) are output in the configured aggregation
-temporality for each instrument kind. For synchronous instruments being output
-with Cumulative temporality, this means converting [Delta to Cumulative](supplementary-guidelines.md#synchronous-example-cumulative-aggregation-temporality)
-aggregation temporality.  For asynchronous instruments being output
-with Delta temporality, this means converting [Cumulative to
-Delta](supplementary-guidelines.md#asynchronous-example-delta-temporality) aggregation
-temporality.
+temporality for each instrument kind. For synchronous instruments with
+Cumulative aggregation temporality, this means
+converting [Delta to Cumulative](supplementary-guidelines.md#synchronous-example-cumulative-aggregation-temporality)
+aggregation temporality. For asynchronous instruments with Delta temporality,
+this means
+converting [Cumulative to Delta](supplementary-guidelines.md#asynchronous-example-delta-temporality)
+aggregation temporality.
 
 The `MetricReader` is not required to ensure data points from a non-SDK
 [MetricProducer](#metricproducer) are output in the configured aggregation
 temporality, as these data points are not collected using OpenTelemetry
 instruments.
 
+The `MetricReader` selection of `temporality` as a function of instrument kind
+influences the persistence of metric data points across collections. For
+synchronous instruments with Cumulative aggregation
+temporality, [MetricReader.Collect](#collect) MUST receive data points exposed
+in previous collections regardless of whether new measurements have been
+recorded. For synchronous instruments with Delta aggregation
+temporality, [MetricReader.Collect](#collect) MUST only receive data points with
+measurements recorded since the previous collection. For asynchronous
+instruments with Delta or Cumulative aggregation
+temporality, [MetricReader.Collect](#collect) MUST only receive data points with
+measurements recorded since the previous collection. These rules apply to all
+metrics, not just those whose [point kinds](./data-model.md#point-kinds)
+includes an aggregation temporality field.
+
+The `MetricReader` selection of `temporality` as a function of instrument kind
+influences the starting timestamp (i.e. `StartTimeUnixNano`) of metrics data
+points received by [MetricReader.Collect](#collect). For instruments with
+Cumulative aggregation temporality, successive data points received by
+successive calls to [MetricReader.Collect](#collect) MUST repeat the same
+starting timestamps (e.g. `(T0, T1], (T0, T2], (T0, T3]`). For instruments with
+Delta aggregation temporality, successive data points received by successive
+calls to [MetricReader.Collect](#collect) MUST advance the starting timestamp (
+e.g. `(T0, T1], (T1, T2], (T2, T3]`). The ending timestamp (i.e. `TimeUnixNano`)
+MUST always be equal to time the metric data point took effect, which is equal
+to when [MetricReader.Collect](#collect) was invoked. These rules apply to all
+metrics, not just those whose [point kinds](./data-model.md#point-kinds) includes
+an aggregation temporality field.
+See [data model temporality](./data-model.md#temporality) for more details.
+
 The SDK MUST support multiple `MetricReader` instances to be registered on the
 same `MeterProvider`, and the [MetricReader.Collect](#collect) invocation on one
 `MetricReader` instance SHOULD NOT introduce side-effects to other `MetricReader`