From b9d347abebbb24f9b21a603efe349ec99cc0f330 Mon Sep 17 00:00:00 2001 From: Nev <54870357+MSNev@users.noreply.github.com> Date: Tue, 8 Oct 2024 20:32:57 -0700 Subject: [PATCH] Introduce the new user-facing Logs API as a placeholder (#4236) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Part of https://github.com/open-telemetry/oteps/pull/265 --------- Co-authored-by: Robert Pająk Co-authored-by: Trask Stalnaker Co-authored-by: Liudmila Molkova --- .gitignore | 5 ++++- CHANGELOG.md | 3 +++ specification/logs/bridge-api.md | 8 ++++++++ specification/logs/event-api.md | 10 ++++++++++ specification/logs/event-sdk.md | 10 ++++++++++ specification/logs/sdk.md | 6 ++++++ 6 files changed, 41 insertions(+), 1 deletion(-) 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 67397925da6..70dd383d8d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -36,6 +36,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/logs/bridge-api.md b/specification/logs/bridge-api.md index 258966c0839..7b8c2b07e92 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -16,6 +16,7 @@ * [Logger operations](#logger-operations) + [Emit a LogRecord](#emit-a-logrecord) + [Enabled](#enabled) +- [Logs Instrumentation API](#logs-instrumentation-api) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -145,6 +146,13 @@ 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 Instrumentation API + +**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). + ## Optional and required parameters The operations defined include various parameters, some of which are marked diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ea5c58116fe..b239ba31cea 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,6 +9,7 @@ +- [Logs Instrumentation API Development](#logs-instrumentation-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -30,6 +31,15 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. +## Logs Instrumentation API Development + +> [!NOTE] +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-api). + +The intent is that this Logs Instrumentation 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. + +No further work is scheduled for the current Events 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..b76632af67d 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,6 +9,7 @@ +- [Logs Instrumentation API Development](#logs-instrumentation-api-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -29,6 +30,15 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. +## Logs Instrumentation API Development + +> [!NOTE] +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-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. + +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/sdk.md b/specification/logs/sdk.md index 5d29e2b6984..5212fa29a77 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -34,6 +34,7 @@ + [Export](#export) + [ForceFlush](#forceflush-2) + [Shutdown](#shutdown-1) +- [Logs Instrumentation API](#logs-instrumentation-api) @@ -538,4 +539,9 @@ return a Failure result. and the destination is unavailable). [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide if they want to make the shutdown timeout configurable. +## Logs Instrumentation API + +> [!NOTE] +> We are currently in the process of defining a new [Logs Instrumentation API](./bridge-api.md#logs-instrumentation-api). + - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md)