From 9fbb75834b3da7d3ee13357a855cc4a520f07c16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 8 Jan 2025 17:38:14 +0100 Subject: [PATCH] Remove deprecated Events API and SDK (#4353) --- CHANGELOG.md | 3 + specification/logs/event-api.md | 163 -------------------------------- specification/logs/event-sdk.md | 121 ------------------------ 3 files changed, 3 insertions(+), 284 deletions(-) delete mode 100644 specification/logs/event-api.md delete mode 100644 specification/logs/event-sdk.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 21208c00da5..20240e2e5e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,9 @@ release. ### Events +- Remove the deprecated Events API and SDK in favor of having Events support in the Logs API and SDK. + ([#4353](https://github.com/open-telemetry/opentelemetry-specification/pull/4353)) + ### Baggage ### Resource diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md deleted file mode 100644 index 7d17f7f9e74..00000000000 --- a/specification/logs/event-api.md +++ /dev/null @@ -1,163 +0,0 @@ -# Events API - -**Status**: [Deprecated](../document-status.md) (was never stabilized), -see [Emit Event](./api.md#emit-an-event) in the Logs API for replacement. - -
-Table of Contents - - - - - -- [Event Data model](#event-data-model) -- [Event API use cases](#event-api-use-cases) -- [EventLoggerProvider](#eventloggerprovider) - * [EventLoggerProvider operations](#eventloggerprovider-operations) - + [Get an EventLogger](#get-an-eventlogger) -- [EventLogger](#eventlogger) - * [EventLogger Operations](#eventlogger-operations) - + [Emit Event](#emit-event) -- [Optional and required parameters](#optional-and-required-parameters) -- [References](#references) - - - -
- -The Event API consists of these main components: - -* [EventLoggerProvider](#eventloggerprovider) is the entry point of the API. It - provides access to `EventLogger`s. -* [EventLogger](#eventlogger) is the component responsible for emitting events. - -## Event Data model - -Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): - ->In computing, a log file is a file that records either events that occur in an ->operating system or other software runs. - -From OpenTelemetry's perspective LogRecords and Events are both represented -using the same [data model](./data-model.md). An Event is a specialized type -of LogRecord, not a separate concept. - -Events are OpenTelemetry's standardized semantic formatting for LogRecords. -Beyond the structure provided by the LogRecord data model, it is helpful for -logs to have a common format within that structure. When OpenTelemetry -instrumentation emits logs, those logs SHOULD be formatted as Events. All -semantic conventions defined for logs MUST be formatted as Events. - -The Event format is as follows. All Events have a -[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md), -and all Events with the same `event.name` MUST conform to the same schema for -both their `Attributes` and their `Body`. - -## Event API use cases - -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 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: - -* Logging from a shared library that must run in many applications. -* A semantic convention needs to be defined. We do not define semantic - conventions for LogRecords that are not Events. -* Analysis by an observability platform is the intended use case. For - example: statistics, indexing, machine learning, session replay. -* Normalizing logging and having a consistent schema across a large - application is helpful. - -If any of these properties fit your requirements, we recommend using the Event API. -Events are described in more detail in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). - -Please note that the OpenTelemetry Log SDK currently lacks a number of advanced -features present in popular logging libraries. For example: pattern logging, file -rotation, network appenders, etc. These features cannot be used with the -OpenTelemetry Event SDK at this time. - -If a logging library is capable of creating logs which correctly map -to the Event data model, logging in this manner is also an acceptable way to -create Events. - -## EventLoggerProvider - -`EventLogger`s can be accessed with a `EventLoggerProvider`. - -Normally, the `EventLoggerProvider` is expected to be accessed from a central place. -Thus, the API SHOULD provide a way to set/register and access a global default -`EventLoggerProvider`. - -### EventLoggerProvider operations - -The `EventLoggerProvider` MUST provide the following functions: - -* Get an `EventLogger` - -#### Get an EventLogger - -This API MUST accept the following parameters: - -* `name`: Specifies the name of the [instrumentation scope](../glossary.md#instrumentation-scope), - such as the [instrumentation library](../glossary.md#instrumentation-library) - (e.g. `io.opentelemetry.contrib.mongodb`), package, module or class name. - If an application or library has built-in OpenTelemetry instrumentation, both - [Instrumented library](../glossary.md#instrumented-library) and - [Instrumentation library](../glossary.md#instrumentation-library) may refer to - the same library. In that scenario, the `name` denotes a module name or component - name within that library or application. - -* `version` (optional): Specifies the version of the instrumentation scope if - the scope has a version (e.g. a library version). Example value: 1.0.0. - -* `schema_url` (optional): Specifies the Schema URL that should be recorded in - the emitted telemetry. - -* `attributes` (optional): Specifies the instrumentation scope attributes to - associate with emitted telemetry. This API MUST be structured to accept a - variable number of attributes, including none. - -The term *identical* applied to `EventLogger`s describes instances where all -parameters are equal. The term *distinct* applied to `EventLogger`s describes -instances where at least one parameter has a different value. - -## EventLogger - -The `EventLogger` is the entrypoint of the Event API, and is responsible for -emitting `Events` as `LogRecord`s. - -### EventLogger Operations - -The `EventLogger` MUST provide functions to: - -#### Emit Event - -The effect of calling this API is to emit an `Event` to the processing pipeline. - -**Parameters:** - -* The `Name` of the Event, as described - in [event.name semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). -* The (`AnyValue`) (optional) `Body` of the Event. -* The `Timestamp` (optional) of the Event. -* The [Context](../context/README.md) (optional) associated with the Event. -* The `SeverityNumber` (optional) of the Event. -* The `Attributes` (optional) of the Event. Event `Attributes` provide - additional details about the Event which are not part of the - well-defined event `Body`. - -## Optional and required parameters - -The operations defined include various parameters, some of which are marked -optional. Parameters not marked optional are required. - -For each optional parameter, the API MUST be structured to accept it, but MUST -NOT obligate a user to provide it. - -For each required parameter, the API MUST be structured to obligate a user to -provide it. - -## References - -- [OTEP0202 Introducing Events and Logs API](https://github.com/open-telemetry/oteps/blob/main/text/0202-events-and-logs-api.md) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md deleted file mode 100644 index 25a66a1734b..00000000000 --- a/specification/logs/event-sdk.md +++ /dev/null @@ -1,121 +0,0 @@ -# Events SDK - -**Status**: [Deprecated](../document-status.md) (was never stabilized), -see the [Logs SDK](./sdk.md) and [Emit Event](./api.md#emit-an-event) in the Logs API for replacement. - -
-Table of Contents - - - - - -- [Logs API Development](#logs-api-development) -- [Overview](#overview) -- [EventLoggerProvider](#eventloggerprovider) - * [EventLoggerProvider Creation](#eventloggerprovider-creation) - * [EventLogger Creation](#eventlogger-creation) - * [Configuration](#configuration) - * [ForceFlush](#forceflush) -- [EventLogger](#eventlogger) - * [Emit Event](#emit-event) - - - -
- -Users of OpenTelemetry need a way for instrumentation interactions with the -OpenTelemetry API to actually produce telemetry. The OpenTelemetry SDK -(henceforth referred to as the SDK) is an implementation of the OpenTelemetry -API that provides users with this functionally. - -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](./api.md). - -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. - -No further work is scheduled for the current Event SDK at this time. - -## Overview - -From OpenTelemetry's perspective LogRecords and Events are both represented -using the same [data model](./event-api.md#event-data-model). Therefore, the default -implementation of an Event SDK MUST generate events using the [Logs Data Model](./data-model.md). - -The SDK MUST use the [Logs SDK](./sdk.md) to generate, process and export `LogRecord`s. - -## EventLoggerProvider - -The `EventLoggerProvider` MUST be implemented as a proxy to an instance of [`LoggerProvider`](./sdk.md#loggerprovider). - -All `LogRecord`s produced by any `EventLogger` from the `EventLoggerProvider` SHOULD be associated with the `Resource` from the provided `LoggerProvider`. - -### EventLoggerProvider Creation - -The SDK SHOULD allow the creation of multiple independent `EventLoggerProvider`s. - -### EventLogger Creation - -It SHOULD only be possible to create `EventLogger` instances through an `EventLoggerProvider` -(see [Events API](event-api.md)). - -The `EventLoggerProvider` MUST implement the [Get an EventLogger API](event-api.md#get-an-eventlogger). - -In the case where an invalid `name` (null or empty string) is specified, a -working `EventLogger` MUST be returned as a fallback rather than returning null or -throwing an exception. Its `name` SHOULD keep the original invalid value, and a -message reporting that the specified value is invalid SHOULD be logged. - -### Configuration - -The `EventLoggerProvider` MUST accept an instance of `LoggerProvider`. Any configuration -related to processing MUST be done by configuring the `LoggerProvider` directly. - -### ForceFlush - -This method provides a way for the provider to notify the delegate `LoggerProvider` -to force all registered [LogRecordProcessors](sdk.md#logrecordprocessor) to immediately export all -`LogRecords` that have not yet been exported. - -## EventLogger - -The `EventLogger` MUST be implemented as a proxy to an instance of [`Logger`](./sdk.md#logger). - -### Emit Event - -Emit a `LogRecord` representing an `Event`. - -**Implementation Requirements:** - -The implementation MUST use the parameters -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 - the `Attributes` provided by the user contain an `event.name` attribute the - value provided in the `Name` takes precedence. -* If provided by the user, the `Body` MUST be used to set - the [Body](./data-model.md#field-body). If not provided, `Body` MUST not be - set. -* If provided by the user, the `Timestamp` MUST be used to set - 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](./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](./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 - logRecord. If not provided, `SeverityNumber` MUST be set - to `SEVERITY_NUMBER_INFO=9`. -* The [Severity Text](./data-model.md#field-severitytext) MUST not be set. -* If provided by the user, the `Attributes` MUST be used to set - the [Attributes](./data-model.md#field-attributes). The user - provided `Attributes` MUST not take over the `event.name` - attribute previously discussed.