diff --git a/CHANGELOG.md b/CHANGELOG.md index ddf9f66a02e..17d34986b20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -77,6 +77,9 @@ release. - Introduce initial placeholder for the new user-facing Logs API, adding references to existing API's informing of the coming changes while the definition is defined. ([#4236](https://github.com/open-telemetry/opentelemetry-specification/pull/4236)) +- Rename Log Bridge API to Logs API. Define the existing Logger methods to be + Log Bridge Operations. Add EmitEvent to the Logger as an Instrumentation Operation. + ([#4259](https://github.com/open-telemetry/opentelemetry-specification/pull/4259)) ### Common diff --git a/specification/README.md b/specification/README.md index ba11a14e703..b79d87a520d 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,7 +29,7 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/README.md) - - [Bridge API](logs/bridge-api.md) + - [API](logs/api.md) - [Event API](logs/event-api.md) - SDK Specification - [Tracing](trace/sdk.md) diff --git a/specification/glossary.md b/specification/glossary.md index c1a67d8187a..3a59616470c 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -196,7 +196,7 @@ concept the attributes of the scope cannot change at runtime. This refers to the `name` and (optional) `version` arguments specified when creating a new `Tracer` or `Meter` (see -[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/bridge-api.md#loggerprovider). +[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/api.md#loggerprovider). The name/version pair identifies the [Instrumentation Scope](#instrumentation-scope), for example the [Instrumentation Library](#instrumentation-library) or another unit of @@ -254,7 +254,7 @@ recommended to call it out specifically. ### Log Appender / Bridge A log appender or bridge is a component which bridges logs from an existing log -API into OpenTelemetry using the [Log Bridge API](./logs/bridge-api.md). The +API into OpenTelemetry using the [Log API](./logs/api.md). The terms "log bridge" and "log appender" are used interchangeably, reflecting that these components bridge data into OpenTelemetry, but are often called appenders in the logging domain. diff --git a/specification/logs/README.md b/specification/logs/README.md index 61de647230d..ecf0e84d0cd 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -140,8 +140,8 @@ Given the above state of the logging space we took the following approach: OpenTelemetry log data model. OpenTelemetry Collector can read such logs and translate them to OpenTelemetry log data model. -- OpenTelemetry defines a Logs Bridge API - for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). Application developers are +- OpenTelemetry defines a Logs API + for [emitting LogRecords](./api.md#emit-a-logrecord). Application developers are NOT encouraged to call this API directly. It is provided for library authors to build [log appender](../glossary.md#log-appender--bridge), which use the API to bridge between existing logging libraries and the OpenTelemetry log @@ -149,7 +149,7 @@ Given the above state of the logging space we took the following approach: features than what is defined in OpenTelemetry. It is NOT a goal of OpenTelemetry to ship a feature-rich logging library. -- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [Bridge API](./bridge-api.md), +- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md), which enables configuration of [processing](./sdk.md#logrecordprocessor) and [exporting](./sdk.md#logrecordexporter) LogRecords. @@ -359,7 +359,7 @@ as parsers, log tailing and rotation. It also enables the possibility to send logs directly to the logging backend without using a log collection agent. To facilitate both approaches described above OpenTelemetry provides -a [Bridge API](./bridge-api.md) and [SDK](./sdk.md), which can be used together with existing +a [API](./api.md) and [SDK](./sdk.md), which can be used together with existing logging libraries to automatically inject the trace context in the emitted logs, and provide an easy way to send the logs via OTLP. Instead of modifying each logging statement, [log appenders](../glossary.md#log-appender--bridge) @@ -444,7 +444,7 @@ standard output. ## Specifications -* [Logs Bridge API](./bridge-api.md) +* [Logs API](./api.md) * [Logs SDK](./sdk.md) * [Logs Data Model](./data-model.md) * [Event API](./event-api.md) diff --git a/specification/logs/bridge-api.md b/specification/logs/api.md similarity index 75% rename from specification/logs/bridge-api.md rename to specification/logs/api.md index e889933e3c0..9ef141cfdd9 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/api.md @@ -1,4 +1,4 @@ -# Logs Bridge API +# Logs API **Status**: [Stable](../document-status.md), except where otherwise specified @@ -13,13 +13,13 @@ * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) - [Logger](#logger) - * [Logger operations](#logger-operations) + * [Log Bridge operations](#log-bridge-operations) + [Emit a LogRecord](#emit-a-logrecord) + [Enabled](#enabled) -- [Logs API](#logs-api) + * [Log Instrumentation operations](#log-instrumentation-operations) + + [Emit an Event](#emit-an-event) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) -- [Artifact Naming](#artifact-naming) - [References](#references) @@ -33,7 +33,7 @@ library authors to build which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. -The Logs Bridge API consist of these main components: +The Logs API consist of these main components: * [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s. * [Logger](#logger) is responsible for emitting logs as @@ -92,18 +92,29 @@ instances where at least one parameter has a different value. ## Logger -The `Logger` is responsible for emitting `LogRecord`s. +The `Logger` is responsible for emitting `LogRecord`s. There are two types of +logging operations: -### Logger operations +* **Log Bridge** operations to be used when receiving data from other logging + libraries. +* **Log Instrumentation** operations to be used when writing instrumentation + for OpenTelemetry. -The `Logger` MUST provide functions to: +The Logger contains methods for both types of operations. The `Logger` MUST +provide a function to: - [Emit a `LogRecord`](#emit-a-logrecord) The `Logger` SHOULD provide functions to: +- [Emit an `Event`](#emit-an-event) - [Report if `Logger` is `Enabled`](#enabled) +### Log Bridge operations + +Log Bridge operations are not intended to be used for writing instrumentation, +and SHOULD include documentation that discourages this use. + #### Emit a LogRecord The effect of calling this API is to emit a `LogRecord` to the processing pipeline. @@ -146,12 +157,31 @@ 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. -## Logs API +### Log Instrumentation operations + +#### Emit an Event **Status**: [Development](../document-status.md) -This set of API functions will provide the capabilities needed to emit a -`LogRecord` as is currently provided by [Events API](./event-api.md). +The effect of calling this API is to emit a `LogRecord` to the processing pipeline +formatted as an [event](./data-model.md#events). + +**Parameters:** + +* The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md) + of the Event. +* [Timestamp](./data-model.md#field-timestamp) (optional) +* [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 `Event`. 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) Event `Attributes` conform + to the [standard definition](../common/README.md#standard-attribute) of an attribute. ## Optional and required parameters @@ -166,22 +196,13 @@ provide it. ## Concurrency requirements -For languages which support concurrent execution the Logs Bridge APIs provide +For languages which support concurrent execution the Logs APIs provide specific guarantees and safeties. **LoggerProvider** - all methods are safe to be called concurrently. **Logger** - all methods are safe to be called concurrently. -## Artifact Naming - -The Logs Bridge API is not intended to be called by application developers -directly, and SHOULD include documentation that discourages direct use. However, -in the event OpenTelemetry were to add a user facing API, the Logs Bridge API would -be a natural starting point. Therefore, Log Bridge API artifact, package, and class -names MUST NOT include the terms "bridge", "appender", or any other qualifier -that would prevent evolution into a user facing API. - ## References - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index d0281c70533..c7e88dd745b 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -9,6 +9,7 @@ - [Design Notes](#design-notes) * [Requirements](#requirements) + * [Events](#events) * [Definitions Used in this Document](#definitions-used-in-this-document) + [Type `any`](#type-any) + [Type `map`](#type-mapstring-any) @@ -97,6 +98,16 @@ The Data Model aims to successfully represent 3 sorts of logs and events: we include in the logs. We can likely modify the source code of the application if needed. +### Events + +**Status**: [Development](../document-status.md) + +Events are OpenTelemetry's standardized format for LogRecords. All semantic +conventions defined for logs SHOULD be formatted as Events. Requirements and details for the Event format can be found in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). + +Events are intended to be used by OpenTelemetry instrumentation. It is not a +requirement that all LogRecords are formatted as Events. + ### Definitions Used in this Document In this document we refer to types `any` and `map`, defined as diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index e84861ec024..74957871fa3 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -34,7 +34,7 @@ The Event API consists of these main components: ## Logs API Development > [!NOTE] -> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api). +> We are currently in the process of defining a new [Logs API](./api.md#logs-api). The intent is that this Logs API will incorporate the current functionality of this existing Events API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. @@ -66,7 +66,7 @@ both their `Attributes` and their `Body`. The Events API was designed to allow shared libraries to emit high quality logs without needing to depend on a third party logger. Unlike the -[Logs Bridge API](./bridge-api.md), instrumentation authors and application +[Logs API](./api.md), instrumentation authors and application developers are encouraged to call this API directly. It is appropriate to use the Event API when these properties fit your requirements: diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 28bd88cee14..37220a42a9b 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -33,7 +33,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. ## Logs API Development > [!NOTE] -> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api). +> We are currently in the process of defining a new [Logs API](./api.md#logs-api). The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. @@ -91,7 +91,7 @@ Emit a `LogRecord` representing an `Event`. **Implementation Requirements:** The implementation MUST use the parameters -to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows: +to [emit a logRecord](./api.md#emit-a-logrecord) as follows: * The `Name` MUST be used to set the `event.name` [Attribute](./data-model.md#field-attributes). If @@ -104,10 +104,10 @@ to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows: the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` MUST be set to the current time when [emit](#emit-event) was called. * The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST not be - set. (NOTE: [emit a logRecord](./bridge-api.md#emit-a-logrecord) will + set. (NOTE: [emit a logRecord](./api.md#emit-a-logrecord) will set `ObservedTimestamp` to the current time when unset.) * If provided by the user, the `Context` MUST be used to set - the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context` + the [Context](./api.md#emit-a-logrecord). If not provided, `Context` MUST be set to the current Context. * If provided by the user, the `SeverityNumber` MUST be used to set the [Severity Number](./data-model.md#field-severitynumber) when emitting the diff --git a/specification/logs/noop.md b/specification/logs/noop.md index d1f4cf6f1a3..6a1d8502106 100644 --- a/specification/logs/noop.md +++ b/specification/logs/noop.md @@ -2,7 +2,7 @@ linkTitle: No-Op ---> -# Logs Bridge API No-Op Implementation +# Logs API No-Op Implementation **Status**: [Stable](../document-status.md) @@ -23,12 +23,12 @@ linkTitle: No-Op Users of OpenTelemetry need a way to disable the API from actually performing any operations. The No-Op OpenTelemetry API implementation (henceforth referred to as the No-Op) provides users with this -functionally. It implements the [OpenTelemetry Logs Bridge API](./bridge-api.md) +functionally. It implements the [OpenTelemetry Logs API](./api.md) so that no telemetry is produced and computation resources are minimized. All language implementations of OpenTelemetry MUST provide a No-Op. -The [Logs Bridge API](./bridge-api.md) defines components with various operations. +The [Logs API](./api.md) defines components with various operations. All No-Op components MUST NOT hold configuration or operational state. All No-op operations MUST accept all defined parameters, MUST NOT validate any arguments received, and MUST NOT return any non-empty error or log any message. @@ -42,7 +42,7 @@ provide the same `LoggerProvider` instances to all creation requests. ### Logger Creation -New `Logger` instances are always created with a [LoggerProvider](./bridge-api.md#loggerprovider). +New `Logger` instances are always created with a [LoggerProvider](./api.md#loggerprovider). Therefore, `LoggerProvider` MUST allow for the creation of `Logger`s. All `Logger`s created MUST be an instance of the [No-Op Logger](#logger). @@ -54,4 +54,4 @@ return the same `Logger` instances to all creation requests. ### Emit LogRecord The No-Op `Logger` MUST allow -for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). +for [emitting LogRecords](./api.md#emit-a-logrecord). diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index d8228b174fa..dfdb4b55fa6 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -60,9 +60,9 @@ The SDK SHOULD allow the creation of multiple independent `LoggerProviders`s. ### Logger Creation It SHOULD only be possible to create `Logger` instances through a `LoggerProvider` -(see [Bridge API](bridge-api.md)). +(see [API](api.md)). -The `LoggerProvider` MUST implement the [Get a Logger API](bridge-api.md#get-a-logger). +The `LoggerProvider` MUST implement the [Get a Logger API](api.md#get-a-logger). The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which @@ -187,7 +187,7 @@ It consists of the following parameters: 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` + 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, @@ -208,7 +208,7 @@ associated with the `LogRecord`. The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from the resolved `Context` (either the explicitly passed `Context` or the -current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord). +current `Context`) when [emitted](./api.md#emit-a-logrecord). Counts for attributes due to collection limits MUST be available for exporters to report as described in @@ -312,7 +312,7 @@ components in the SDK: #### OnEmit -`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-a-logrecord). This +`OnEmit` is called when a `LogRecord` is [emitted](api.md#emit-a-logrecord). This method is called synchronously on the thread that emitted the `LogRecord`, therefore it SHOULD NOT block or throw exceptions. @@ -542,6 +542,6 @@ authors MAY decide if they want to make the shutdown timeout configurable. ## Logs API > [!NOTE] -> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api). +> We are currently in the process of defining a new [Logs API](./api.md#logs-api). - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) diff --git a/specification/logs/supplementary-guidelines.md b/specification/logs/supplementary-guidelines.md index 026951938b6..8108c767722 100644 --- a/specification/logs/supplementary-guidelines.md +++ b/specification/logs/supplementary-guidelines.md @@ -1,7 +1,7 @@ # Supplementary Guidelines Note: this document is NOT a spec, it is provided to support the Logs -[API](./bridge-api.md) and [SDK](./sdk.md) specifications, it does NOT add any +[API](./api.md) and [SDK](./sdk.md) specifications, it does NOT add any extra requirements to the existing specifications.
@@ -34,8 +34,8 @@ and is [one of the supported](README.md#direct-to-collector) log collection approaches. The log appender implementation will typically acquire a -[Logger](./bridge-api.md#logger), then -call [Emit LogRecord](./bridge-api.md#emit-a-logrecord) for `LogRecord`s +[Logger](./api.md#logger), then +call [Emit LogRecord](./api.md#emit-a-logrecord) for `LogRecord`s received from the application. [Implicit Context Injection](#implicit-context-injection) @@ -62,7 +62,7 @@ popular logging library. If the logging library has a concept that is similar to OpenTelemetry's definition of the [Instrumentation Scope's](../glossary.md#instrumentation-scope) name, then the appender's implementation should use that value as the -name parameter when [obtaining the Logger](./bridge-api.md#get-a-logger). +name parameter when [obtaining the Logger](./api.md#get-a-logger). This is for example applicable to: @@ -72,7 +72,7 @@ This is for example applicable to: Appenders should avoid setting any attributes of the Instrumentation Scope. Doing so may result in different appenders setting different attributes on the same Instrumentation Scope, obtained with the same identity of the -[Logger](./bridge-api.md#get-a-logger), which, according to the specification, +[Logger](./api.md#get-a-logger), which, according to the specification, is an error. ### Context @@ -81,13 +81,13 @@ is an error. When Context is implicitly available (e.g. in Java) the Appender can rely on automatic context propagation by NOT explicitly setting `Context` when -calling [emit a LogRecord](./bridge-api.md#emit-a-logrecord). +calling [emit a LogRecord](./api.md#emit-a-logrecord). Some log libraries have mechanisms specifically tailored for injecting contextual information into logs, such as MDC in Log4j. When available, it may be preferable to use these mechanisms to set the Context. A log appender can then fetch the Context and explicitly set it when -calling [emit a LogRecord](./bridge-api.md#emit-a-logrecord). This allows the correct Context +calling [emit a LogRecord](./api.md#emit-a-logrecord). This allows the correct Context to be included even when log records are emitted asynchronously, which can otherwise lead the Context to be incorrect. @@ -100,7 +100,7 @@ In order for `TraceContext` to be recorded in `LogRecord`s in languages where the Context must be provided explicitly (e.g. Go), the end user must capture the Context and explicitly pass it to the logging subsystem. The log appender must take this Context and explicitly set it when -calling [emit a LogRecord](./bridge-api.md#emit-a-logrecord). +calling [emit a LogRecord](./api.md#emit-a-logrecord). Support for OpenTelemetry for logging libraries in these languages typically can be implemented in the form of logger wrappers that can capture the context once,