diff --git a/.gitignore b/.gitignore index c9508b6a86a..7aadede2c9e 100644 --- a/.gitignore +++ b/.gitignore @@ -30,4 +30,7 @@ node_modules/ package-lock.json # Visual Studio Code -.vscode \ No newline at end of file +.vscode + +# Visual Studio +.vs \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index df9d5bca1e6..d765f2e7732 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -34,6 +34,9 @@ release. ([#4221](https://github.com/open-telemetry/opentelemetry-specification/pull/4221)) - Make all fields as identifying for Logger. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) +- 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)) ### Events diff --git a/specification/README.md b/specification/README.md index d1136d70243..a4bce3cfb56 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,6 +29,7 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/README.md) + - [Public API](logs/public-api.md) - [Bridge API](logs/bridge-api.md) - [Event API](logs/event-api.md) - SDK Specification diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 258966c0839..7d24ca8ab4d 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -9,6 +9,7 @@ +- [Public API Development](#public-api-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) @@ -44,6 +45,14 @@ graph TD B -->|Emit| C(LogRecord) ``` +## Public API Development + +We are currently in the process of defining a new [user-facing Logs API](./public-api.md). Unlike this Logs Bridge API, the new API is intended to be called by both application developers and logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Logs Bridge API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Log Bridge API at this time. + ## LoggerProvider `Logger`s can be accessed with a `LoggerProvider`. diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ea5c58116fe..ea556a6c589 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,6 +9,7 @@ +- [Public API Development](#public-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -30,6 +31,14 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. +## Public API Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Event API definition at this time. + ## Event Data model Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 1a9bc0ee829..b1327548509 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,6 +9,7 @@ +- [Public API/SDK Development](#public-apisdk-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -29,6 +30,14 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. +## Public API/SDK Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API will incorporate the current functionality of this existing API and once it is defined and implemented, the Event API 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 diff --git a/specification/logs/public-api.md b/specification/logs/public-api.md new file mode 100644 index 00000000000..56df03b2a77 --- /dev/null +++ b/specification/logs/public-api.md @@ -0,0 +1,40 @@ +# Public Logs API + +**Status**: [Development](../document-status.md), except where otherwise specified + +
+Table of Contents + + + + + +- [Logger](#logger) + * [Logger operations](#logger-operations) +- [References](#references) + + + +
+ +Note: this document is a work in progress as we move towards defining a user-facing Logs API. Unlike the current [Logs Bridge API](./bridge-api.md), this new API is intended to be called by both application developers and logging +library authors to build +[log appenders](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), +which use this API to bridge between existing logging libraries and the +OpenTelemetry log data model. + +## Logger + +The `Logger` is responsible for emitting `LogRecord`s. + +### Logger operations + +The full set of operations that a `Logger` will provide is not yet defined. The +intent is that is will provide the capabalities needed to emit a `LogRecord` as is currently provided by + +* [Logs Bridge API](./bridge-api.md) +* [Events API](./event-api.md) + +## References + +- [OTEP0265 Event Basics](https://github.com/open-telemetry/oteps/blob/main/text/0265-event-vision.md#api) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 5d29e2b6984..896972e7052 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,6 +7,7 @@ +- [Public API/SDK Development](#public-apisdk-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -46,6 +47,14 @@ API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. +## Public API/SDK Development + +Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). + +The intent is that this new API/SDK will incorporate the current functionality of this existing API/SDK and once it is defined and implemented, this SDK usage will be migrated, deprecated, renamed and eventually removed. + +No further work is scheduled for the current Logging SDK definition at this time. + ## LoggerProvider A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md)