Add Tracer#Enabled, Instrument#Enabled and corresponding SDK behavior (…

…#4063) Builds off #4020 to extend the `Enabled` API to `Tracer` and metrics `Instrument`. Adds language to Log SDK, Metrics SDK, and Trace SDK for how scope config is used to resolve the `Enabled` operation. This was discussed in #3867 but punted on in #3877 as [discussed here](#3877 (comment)). --------- Co-authored-by: Robert Pająk <[email protected]> Co-authored-by: Trask Stalnaker <[email protected]> Co-authored-by: Reiley Yang <[email protected]>
open-telemetry · Jun 3, 2024 · d0bfe08 · d0bfe08
1 parent 7deeee8
commit d0bfe08
Show file tree

Hide file tree

Showing 6 changed files with 101 additions and 6 deletions.
diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md
@@ -107,11 +107,11 @@ The `Logger` is responsible for emitting `LogRecord`s.
 
 The `Logger` MUST provide functions to:
 
-- Emit a `LogRecord`
+- [Emit a `LogRecord`](#emit-a-logrecord)
 
 The `Logger` SHOULD provide functions to:
 
-- Report if `Enabled` for a `LogRecord`
+- [Report if `Logger` is `Enabled`](#enabled)
 
 #### Emit a LogRecord
 
@@ -144,12 +144,13 @@ added in the future, therefore, the API MUST be structured in a way for
 parameters to be added.
 
 This API MUST return a language idiomatic boolean type. A returned value of
-`true` means logging is enabled for the provided arguments, and a returned
-value of `false` means the logging is disabled for the provided arguments.
+`true` means the `Logger` is enabled for the provided arguments, and a returned
+value of `false` means the `Logger` is disabled for the provided arguments.
 
 The returned value is not always static, it can change over time. The API
-SHOULD be documented that Logs Bridge API developers needs to call this API each time they generate
-a `LogRecord` to ensure they have the most up-to-date response.
+SHOULD be documented that instrumentation authors needs to call this API each
+time they [emit a LogRecord](#emit-a-logrecord) to ensure they have the most
+up-to-date response.
 
 ## Optional and required parameters
 

diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md
@@ -184,6 +184,14 @@ It consists of the following parameters:
  If a `Logger` is disabled, it MUST behave equivalently
  to [No-op Logger](./noop.md#logger).
 
+ The value of `disabled` MUST be used to resolve whether a `Logger`
+ is [Enabled](./bridge-api.md#enabled). If `disabled` is `true`, `Enabled`
+ returns `false`. If `disabled` is `false`, `Enabled` returns `true`. It is not
+ necessary for implementations to ensure that changes to `disabled` are
+ immediately visible to callers of `Enabled`. I.e. atomic, volatile,
+ synchronized, or equivalent memory semantics to avoid stale reads are
+ discouraged to prioritize performance over immediate consistency.
+
 ## Additional LogRecord interfaces
 
 In this document we refer to `ReadableLogRecord` and `ReadWriteLogRecord`, defined as follows.

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -28,6 +28,8 @@ linkTitle: API
  + [Synchronous and Asynchronous instruments](#synchronous-and-asynchronous-instruments)
  - [Synchronous Instrument API](#synchronous-instrument-api)
  - [Asynchronous Instrument API](#asynchronous-instrument-api)
+ * [General operations](#general-operations)
+ + [Enabled](#enabled)
  * [Counter](#counter)
  + [Counter creation](#counter-creation)
  + [Counter operations](#counter-operations)
@@ -473,6 +475,31 @@ what is the idiomatic approach (e.g. it could be an additional
 parameter to the callback function, or captured by the lambda closure,
 or something else).
 
+### General operations
+
+All instruments SHOULD provide functions to:
+
+* [Report if instrument is `Enabled`](#enabled)
+
+#### Enabled
+
+**Status**: [Experimental](../document-status.md)
+
+To help users avoid performing computationally expensive operations when
+recording measurements, instruments SHOULD provide this `Enabled` API.
+
+There are currently no required parameters for this API. Parameters can be
+added in the future, therefore, the API MUST be structured in a way for
+parameters to be added.
+
+This API MUST return a language idiomatic boolean type. A returned value of
+`true` means the instrument is enabled for the provided arguments, and a returned
+value of `false` means the instrument is disabled for the provided arguments.
+
+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.
+
 ### Counter
 
 `Counter` is a [synchronous Instrument](#synchronous-instrument-api) which supports

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -49,6 +49,7 @@ linkTitle: SDK
  * [Instrument unit](#instrument-unit)
  * [Instrument description](#instrument-description)
  * [Instrument advisory parameters](#instrument-advisory-parameters)
+ * [Instrument enabled](#instrument-enabled)
 - [Attribute limits](#attribute-limits)
 - [Exemplar](#exemplar)
  * [ExemplarFilter](#exemplarfilter)
@@ -857,6 +858,10 @@ It consists of the following parameters:
  If a `Meter` is disabled, it MUST behave equivalently
  to [No-op Meter](./noop.md#meter).
 
+ The value of `disabled` MUST be used to resolve whether an instrument
+ is [Enabled](./api.md#enabled). See [Instrument Enabled](#instrument-enabled)
+ for details.
+
 ### Duplicate instrument registration
 
 A _duplicate instrument registration_ occurs when more than one Instrument of
@@ -947,6 +952,27 @@ different advisory parameters, the Meter MUST return an instrument using the
 first-seen advisory parameters and log an appropriate error as described in
 [duplicate instrument registrations](#duplicate-instrument-registration).
 
+### Instrument enabled
+
+**Status**: [Experimental](../document-status.md)
+
+The instrument [Enabled](./api.md#enabled) operation MUST return `false` if any
+of the following conditions are true, and `true` otherwise:
+
+* The [MeterConfig](#meterconfig) of the `Meter` used to create the instrument
+ has parameter `disabled=true`.
+* All [resolved views](#measurement-processing) for the instrument are
+ configured with the [Drop Aggregation](#drop-aggregation).
+
+Note: If a user makes no configuration changes, `Enabled` returns `true` since by
+default `MeterConfig.disabled=false` and instruments use the default
+aggregation when no matching views match the instrument.
+
+It is not necessary for implementations to ensure that changes
+to `MeterConfig.disabled` are immediately visible to callers of `Enabled`. I.e.
+atomic, volatile, synchronized, or equivalent memory semantics to avoid stale
+reads are discouraged to prioritize performance over immediate consistency.
+
 ## Attribute limits
 
 **Status**: [Stable](../document-status.md)

diff --git a/specification/trace/api.md b/specification/trace/api.md
@@ -21,6 +21,7 @@ linkTitle: API
 - [Context Interaction](#context-interaction)
 - [Tracer](#tracer)
  * [Tracer operations](#tracer-operations)
+ + [Enabled](#enabled)
 - [SpanContext](#spancontext)
  * [Retrieving the TraceId and SpanId](#retrieving-the-traceid-and-spanid)
  * [IsValid](#isvalid)
@@ -203,6 +204,30 @@ The `Tracer` MUST provide functions to:
 
 - [Create a new `Span`](#span-creation) (see the section on `Span`)
 
+The `Tracer` SHOULD provide functions to:
+
+- [Report if `Tracer` is `Enabled`](#enabled)
+
+#### Enabled
+
+**Status**: [Experimental](../document-status.md)
+
+To help users avoid performing computationally expensive operations when
+creating `Span`s, a `Tracer` SHOULD provide this `Enabled` API.
+
+There are currently no required parameters for this API. Parameters can be
+added in the future, therefore, the API MUST be structured in a way for
+parameters to be added.
+
+This API MUST return a language idiomatic boolean type. A returned value of
+`true` means the `Tracer` is enabled for the provided arguments, and a returned
+value of `false` means the `Tracer` is disabled for the provided arguments.
+
+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 [create a new `Span`](#span-creation) to ensure they have the most
+up-to-date response.
+
 ## SpanContext
 
 A `SpanContext` represents the portion of a `Span` which must be serialized and

diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md
@@ -179,6 +179,14 @@ It consists of the following parameters:
  If a `Tracer` is disabled, it MUST behave equivalently
  to [No-op Tracer](./api.md#behavior-of-the-api-in-the-absence-of-an-installed-sdk).
 
+ The value of `disabled` MUST be used to resolve whether a `Tracer`
+ is [Enabled](./api.md#enabled). If `disabled` is `true`, `Enabled`
+ returns `false`. If `disabled` is `false`, `Enabled` returns `true`. It is not
+ necessary for implementations to ensure that changes to `disabled` are
+ immediately visible to callers of `Enabled`. I.e. atomic, volatile,
+ synchronized, or equivalent memory semantics to avoid stale reads are
+ discouraged to prioritize performance over immediate consistency.
+
 ## Additional Span Interfaces
 
 The [API-level definition for Span's interface](api.md#span-operations)