diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 001bd00d345..ab7eee43681 100644 --- 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 index fb84188f74f..5efb354db75 100644 --- 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 index 6ca88de654e..a0430082014 100644 --- 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 index 5ccd78ef69c..2b9747fa97f 100644 --- 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 index 88d4b1cd168..a2730cdbf68 100644 --- 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 index feb2933d443..4c41bb62d20 100644 --- 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)