From 7c78efff144eaf1620880994ec842c4f1f830f3a Mon Sep 17 00:00:00 2001 From: Nev Wylie <54870357+MSNev@users.noreply.github.com> Date: Tue, 1 Oct 2024 11:00:48 -0700 Subject: [PATCH] Rename Public API to Instrumentation API and move into the bridge api --- specification/README.md | 1 - specification/logs/bridge-api.md | 20 +++++++++------- specification/logs/event-api.md | 8 ++++--- specification/logs/event-sdk.md | 6 ++--- specification/logs/public-api.md | 40 -------------------------------- specification/logs/sdk.md | 14 ++++------- 6 files changed, 24 insertions(+), 65 deletions(-) delete mode 100644 specification/logs/public-api.md diff --git a/specification/README.md b/specification/README.md index a4bce3cfb56..d1136d70243 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,7 +29,6 @@ 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 7d24ca8ab4d..f66988fcb3b 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -9,7 +9,6 @@ -- [Public API Development](#public-api-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) @@ -17,6 +16,7 @@ * [Logger operations](#logger-operations) + [Emit a LogRecord](#emit-a-logrecord) + [Enabled](#enabled) +- [Instrumentation API](#instrumentation-api) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -45,14 +45,6 @@ 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`. @@ -154,6 +146,16 @@ 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. +## Instrumentation API + +**Status**: [Development](../document-status.md) + +This set of API functions 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) + ## 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 ea556a6c589..61c77140377 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,7 +9,7 @@ -- [Public API Development](#public-api-development) +- [Instrumentation API Development](#instrumentation-api-development) - [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) @@ -31,9 +31,11 @@ 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 +## Instrumentation API Development -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). +**Status**: [Development](../document-status.md) + +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). 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. diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index b1327548509..3fce8b0c4b4 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,7 +9,7 @@ -- [Public API/SDK Development](#public-apisdk-development) +- [Instrumentation API Development](#instrumentation-api-development) - [Overview](#overview) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider Creation](#eventloggerprovider-creation) @@ -30,9 +30,9 @@ API that provides users with this functionally. All implementations of the OpenTelemetry API MUST provide an SDK. -## Public API/SDK Development +## Instrumentation API Development -Note!: We are currently in the process of defining a new [user-facing Logs API](./public-api.md). +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). 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. diff --git a/specification/logs/public-api.md b/specification/logs/public-api.md deleted file mode 100644 index 56df03b2a77..00000000000 --- a/specification/logs/public-api.md +++ /dev/null @@ -1,40 +0,0 @@ -# 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 896972e7052..a4ef413ab0a 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,7 +7,6 @@ -- [Public API/SDK Development](#public-apisdk-development) - [LoggerProvider](#loggerprovider) * [LoggerProvider Creation](#loggerprovider-creation) * [Logger Creation](#logger-creation) @@ -35,6 +34,7 @@ + [Export](#export) + [ForceFlush](#forceflush-2) + [Shutdown](#shutdown-1) +- [Instrumentation API](#instrumentation-api) @@ -47,14 +47,6 @@ 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) @@ -547,4 +539,8 @@ 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. +## Instrumentation API + +Note!: We are currently in the process of defining a new [Instrumentation API](./bridge-api.md#instrumentation-api). + - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md)