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 375fd1f47de..d6d9440ab58 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,6 +38,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 @@ -55,6 +58,8 @@ release. - Define equality for attributes and collection of attributes. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) +- Update Instrumentation Scope glossary entry with correct identifying fields + ([#4244](https://github.com/open-telemetry/opentelemetry-specification/pull/4244)) ### Supplementary Guidelines diff --git a/specification/glossary.md b/specification/glossary.md index 55504f499f5..c1a67d8187a 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -172,16 +172,20 @@ reasonable instrumentation scope. The most common approach is to use the scopes are also common, e.g. a module, a package, or a class can be chosen as the instrumentation scope. -If the unit of code has a version then the instrumentation scope is defined by -the (name,version) pair otherwise the version is omitted and only the name is -used. The name or (name,version) pair uniquely identify the logical unit of the -code that emits the telemetry. A typical approach to ensure uniqueness is to use -fully qualified name of the emitting code (e.g. fully qualified library name or -fully qualified class name). +The instrumentation scope is defined by the +(name,version,schema_url,attributes) tuple where version, schema_url, and +attributes are optional. This tuple uniquely identifies the logical unit of the +code that emits the telemetry. A typical approach to ensure uniqueness is to +use the fully qualified name of the emitting code (e.g. fully qualified library +name or fully qualified class name). The instrumentation scope is used to obtain a [Tracer, Meter, or Logger](#tracer-name--meter-name--logger-name). +The instrumentation scope's optional Schema URL identifies the [Telemetry +Schema](schemas/README.md) that the instrumentation's emitted +telemetry conforms to. + The instrumentation scope may have zero or more additional attributes that provide additional information about the scope. For example for a scope that specifies an instrumentation library an additional attribute may be recorded to denote the URL of the 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)