Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Tracer#Enabled, Instrument#Enabled and corresponding SDK behavior #4063

Merged
merged 9 commits into from
Jun 3, 2024
13 changes: 7 additions & 6 deletions specification/logs/bridge-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
8 changes: 8 additions & 0 deletions specification/logs/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
trask marked this conversation as resolved.
Show resolved Hide resolved

## Additional LogRecord interfaces

In this document we refer to `ReadableLogRecord` and `ReadWriteLogRecord`, defined as follows.
Expand Down
23 changes: 23 additions & 0 deletions specification/metrics/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,29 @@ The `Meter` MUST provide functions to create new [Instruments](#instrument):

Also see the respective sections below for more information on instrument creation.

The `Meter` SHOULD provide functions to:

* [Report if `Meter` is `Enabled`](#enabled)

#### Enabled

**Status**: [Experimental](../document-status.md)

To help users avoid performing computationally expensive operations when
recording measurements, a `Meter` 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 `Meter` is enabled for the provided arguments, and a returned
value of `false` means the `Meter` 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.

## Instrument

Instruments are used to report [Measurements](#measurement). Each Instrument
Expand Down
8 changes: 8 additions & 0 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -857,6 +857,14 @@ 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 a `Meter`
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.

### Duplicate instrument registration

A _duplicate instrument registration_ occurs when more than one Instrument of
Expand Down
24 changes: 24 additions & 0 deletions specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -203,6 +203,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 q new `Span`](#span-creation) to ensure they have the most
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
up-to-date response.

## SpanContext

A `SpanContext` represents the portion of a `Span` which must be serialized and
Expand Down
8 changes: 8 additions & 0 deletions specification/trace/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
discouraged to prioritize performance over immediate consistency.

## Additional Span Interfaces

The [API-level definition for Span's interface](api.md#span-operations)
Expand Down
Loading