From cf2f7b665b4af6879abaa8dfe3f4caacdae553ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 15 Jan 2025 22:33:03 +0100 Subject: [PATCH] logs: Remove Events operations in favor of making whole Logger user-facing (#4352) --- CHANGELOG.md | 5 ++++ specification/logs/api.md | 53 +++++---------------------------------- 2 files changed, 11 insertions(+), 47 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index be1e56c13bb..2c9b1faea49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,11 @@ release. ### Logs +- Remove `Logger`'s Log Instrumentation operations. + ([#4352](https://github.com/open-telemetry/opentelemetry-specification/pull/4352)) +- Make all `Logger` operations user-facing. + ([#4352](https://github.com/open-telemetry/opentelemetry-specification/pull/4352)) + ### Events - Remove the deprecated Events API and SDK in favor of having Events support in the Logs API and SDK. diff --git a/specification/logs/api.md b/specification/logs/api.md index 24328b2e70b..22a80d0d4ce 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -18,11 +18,8 @@ aliases: [bridge-api] * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) - [Logger](#logger) - * [Log Bridge operations](#log-bridge-operations) - + [Emit a LogRecord](#emit-a-logrecord) - + [Enabled](#enabled) - * [Log Instrumentation operations](#log-instrumentation-operations) - + [Emit an Event](#emit-an-event) + * [Emit a LogRecord](#emit-a-logrecord) + * [Enabled](#enabled) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [References](#references) @@ -97,30 +94,17 @@ instances where at least one parameter has a different value. ## Logger -The `Logger` is responsible for emitting `LogRecord`s. There are two types of -logging operations: +The `Logger` is responsible for emitting `LogRecord`s. -* **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 contains methods for both types of operations. The `Logger` MUST -provide a function to: +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 +### Emit a LogRecord The effect of calling this API is to emit a `LogRecord` to the processing pipeline. @@ -139,7 +123,7 @@ The API MUST accept the following parameters: - [Attributes](./data-model.md#field-attributes) (optional) - **Status**: [Development](../document-status.md) - [Event Name](./data-model.md#field-eventname) (optional) -#### Enabled +### Enabled **Status**: [Development](../document-status.md) @@ -163,31 +147,6 @@ 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. -### Log Instrumentation operations - -#### Emit an Event - -**Status**: [Development](../document-status.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:** - -* [Event Name](./data-model.md#field-eventname) (required) -* [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 The operations defined include various parameters, some of which are marked