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

Define Enabled parameters for Logger #4203

Merged
merged 14 commits into from
Sep 20, 2024
Merged
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,8 @@ release.
([#4067](https://github.com/open-telemetry/opentelemetry-specification/pull/4067))
- Clarify that `Export` MUST NOT be called by simple and batching processors concurrently.
([#4173](https://github.com/open-telemetry/opentelemetry-specification/pull/4173))
- Define `Enabled` parameters for `Logger`.
([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203))

### Events

Expand Down
40 changes: 26 additions & 14 deletions specification/logs/bridge-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,18 +119,17 @@ The effect of calling this API is to emit a `LogRecord` to the processing pipeli

The API MUST accept the following parameters:

- [Timestamp](./data-model.md#field-timestamp)
- [Observed Timestamp](./data-model.md#field-observedtimestamp). If unspecified the
- [Timestamp](./data-model.md#field-timestamp) (optional)
cijothomas marked this conversation as resolved.
Show resolved Hide resolved
- [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified the
implementation SHOULD set it equal to the current time.
- The [Context](../context/README.md) associated with the `LogRecord`. The API
MAY implicitly use the current Context as a default
behavior.
- [Severity Number](./data-model.md#field-severitynumber)
- [Severity Text](./data-model.md#field-severitytext)
- [Body](./data-model.md#field-body)
- [Attributes](./data-model.md#field-attributes)

All parameters are optional.
- The [Context](../context/README.md) associated with the `LogRecord`.
When implicit Context is supported, then this parameter SHOULD be optional and
if unspecified then MUST use current Context.
When only explicit Context is supported, this parameter SHOULD be required.
- [Severity Number](./data-model.md#field-severitynumber) (optional)
- [Severity Text](./data-model.md#field-severitytext) (optional)
- [Body](./data-model.md#field-body) (optional)
- [Attributes](./data-model.md#field-attributes) (optional)

#### Enabled

Expand All @@ -139,9 +138,22 @@ All parameters are optional.
To help users avoid performing computationally expensive operations when
generating a `LogRecord`, a `Logger` 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.
The API SHOULD accept the following parameters:

- The [Context](../context/README.md) to be associated with the `LogRecord`.
When implicit Context is supported, then this parameter SHOULD be optional and
if unspecified then MUST use current Context.
When only explicit Context is supported, this parameter SHOULD be required.
pellared marked this conversation as resolved.
Show resolved Hide resolved
- [Severity Number](./data-model.md#field-severitynumber) (optional)

Optional parameters can be added in the future, therefore,
the API MUST be structured in a way for optional parameters to be added.
pellared marked this conversation as resolved.
Show resolved Hide resolved

It SHOULD be possible to distinguish between an unspecified parameter value from
a parameter value set explicitly to a valid default value of given type
(e.g. distinguish unspecified attributes for empty attributes). The exception
from this rule is when the default value of given type is not seen as a valid
value like 0 for [Severity Number](./data-model.md#field-severitynumber).

This API MUST return a language idiomatic boolean type. A returned value of
`true` means the `Logger` is enabled for the provided arguments, and a returned
Expand Down
Loading