Add EmitEvent to Logs API (#4259)

Continuing the work of implementing [OTEP
265](https://github.com/open-telemetry/oteps/blob/main/text/0265-event-vision.md),
this PR adds the EmitEvent method to the Log API.

Deprecating the experimental Event API and SDK can be handled in a
follow up PR.

Java prototype:
open-telemetry/opentelemetry-java#6761

---------

Co-authored-by: Trask Stalnaker <[email protected]>
Co-authored-by: Robert Pająk <[email protected]>

CHANGELOG.md

@@ -77,6 +77,9 @@ release.
 - 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))
+- Rename Log Bridge API to Logs API. Define the existing Logger methods to be
+  Log Bridge Operations. Add EmitEvent to the Logger as an Instrumentation Operation.
+  ([#4259](https://github.com/open-telemetry/opentelemetry-specification/pull/4259))
 
 ### Common
 

specification/README.md

@@ -29,7 +29,7 @@ path_base_for_github_subdir:
   - [Tracing](trace/api.md)
   - [Metrics](metrics/api.md)
   - [Logs](logs/README.md)
-    - [Bridge API](logs/bridge-api.md)
+    - [API](logs/api.md)
     - [Event API](logs/event-api.md)
 - SDK Specification
   - [Tracing](trace/sdk.md)

specification/glossary.md

@@ -196,7 +196,7 @@ concept the attributes of the scope cannot change at runtime.
 
 This refers to the `name` and (optional) `version` arguments specified when
 creating a new `Tracer` or `Meter` (see
-[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/bridge-api.md#loggerprovider).
+[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/api.md#loggerprovider).
 The name/version pair identifies the
 [Instrumentation Scope](#instrumentation-scope), for example the
 [Instrumentation Library](#instrumentation-library) or another unit of
@@ -254,7 +254,7 @@ recommended to call it out specifically.
 ### Log Appender / Bridge
 
 A log appender or bridge is a component which bridges logs from an existing log
-API into OpenTelemetry using the [Log Bridge API](./logs/bridge-api.md). The
+API into OpenTelemetry using the [Log API](./logs/api.md). The
 terms "log bridge" and "log appender" are used interchangeably, reflecting that
 these components bridge data into OpenTelemetry, but are often called appenders
 in the logging domain.

specification/logs/README.md

@@ -140,16 +140,16 @@ Given the above state of the logging space we took the following approach:
   OpenTelemetry log data model. OpenTelemetry Collector can read such logs and
   translate them to OpenTelemetry log data model.
 
-- OpenTelemetry defines a Logs Bridge API
-  for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). Application developers are
+- OpenTelemetry defines a Logs API
+  for [emitting LogRecords](./api.md#emit-a-logrecord). Application developers are
   NOT encouraged to call this API directly. It is provided for library authors
   to build [log appender](../glossary.md#log-appender--bridge), which use
   the API to bridge between existing logging libraries and the OpenTelemetry log
   data model. Existing logging libraries generally provide a much richer set of
   features than what is defined in OpenTelemetry. It is NOT a goal of
   OpenTelemetry to ship a feature-rich logging library.
 
-- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [Bridge API](./bridge-api.md),
+- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md),
   which enables configuration of [processing](./sdk.md#logrecordprocessor)
   and [exporting](./sdk.md#logrecordexporter) LogRecords.
 
@@ -359,7 +359,7 @@ as parsers, log tailing and rotation. It also enables the possibility to send
 logs directly to the logging backend without using a log collection agent.
 
 To facilitate both approaches described above OpenTelemetry provides
-a [Bridge API](./bridge-api.md) and [SDK](./sdk.md), which can be used together with existing
+a [API](./api.md) and [SDK](./sdk.md), which can be used together with existing
 logging libraries to automatically inject the trace context in the emitted logs,
 and provide an easy way to send the logs via OTLP. Instead of
 modifying each logging statement, [log appenders](../glossary.md#log-appender--bridge)
@@ -444,7 +444,7 @@ standard output.
 
 ## Specifications
 
-* [Logs Bridge API](./bridge-api.md)
+* [Logs API](./api.md)
 * [Logs SDK](./sdk.md)
 * [Logs Data Model](./data-model.md)
 * [Event API](./event-api.md)

specification/logs/bridge-api.md → specification/logs/api.md

@@ -1,4 +1,4 @@
-# Logs Bridge API
+# Logs API
 
 **Status**: [Stable](../document-status.md), except where otherwise specified
 
@@ -13,13 +13,13 @@
   * [LoggerProvider operations](#loggerprovider-operations)
     + [Get a Logger](#get-a-logger)
 - [Logger](#logger)
-  * [Logger operations](#logger-operations)
+  * [Log Bridge operations](#log-bridge-operations)
     + [Emit a LogRecord](#emit-a-logrecord)
     + [Enabled](#enabled)
-- [Logs API](#logs-api)
+  * [Log Instrumentation operations](#log-instrumentation-operations)
+    + [Emit an Event](#emit-an-event)
 - [Optional and required parameters](#optional-and-required-parameters)
 - [Concurrency requirements](#concurrency-requirements)
-- [Artifact Naming](#artifact-naming)
 - [References](#references)
 
 <!-- tocstop -->
@@ -33,7 +33,7 @@ library authors to build
 which use this API to bridge between existing logging libraries and the
 OpenTelemetry log data model.</b>
 
-The Logs Bridge API consist of these main components:
+The Logs API consist of these main components:
 
 * [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s.
 * [Logger](#logger) is responsible for emitting logs as
@@ -92,18 +92,29 @@ instances where at least one parameter has a different value.
 
 ## Logger
 
-The `Logger` is responsible for emitting `LogRecord`s.
+The `Logger` is responsible for emitting `LogRecord`s. There are two types of
+logging operations:
 
-### Logger operations
+* **Log Bridge** operations to be used when receiving data from other logging
+  libraries.
+* **Log Instrumentation** operations to be used when writing instrumentation
+  for OpenTelemetry.
 
-The `Logger` MUST provide functions to:
+The Logger contains methods for both types of operations. The `Logger` MUST
+provide a function to:
 
 - [Emit a `LogRecord`](#emit-a-logrecord)
 
 The `Logger` SHOULD provide functions to:
 
+- [Emit an `Event`](#emit-an-event)
 - [Report if `Logger` is `Enabled`](#enabled)
 
+### Log Bridge operations
+
+Log Bridge operations are not intended to be used for writing instrumentation,
+and SHOULD include documentation that discourages this use.
+
 #### Emit a LogRecord
 
 The effect of calling this API is to emit a `LogRecord` to the processing pipeline.
@@ -146,12 +157,31 @@ 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 API
+### Log Instrumentation operations
+
+#### Emit an Event
 
 **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).
+The effect of calling this API is to emit a `LogRecord` to the processing pipeline
+formatted as an [event](./data-model.md#events).
+
+**Parameters:**
+
+* The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md)
+  of the Event.
+* [Timestamp](./data-model.md#field-timestamp) (optional)
+* [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified
+  the implementation SHOULD set it equal to the current time.
+* The [Context](../context/README.md) associated with the `Event`. When implicit
+  Context is supported, then this parameter SHOULD be optional and if unspecified
+  then MUST use current Context. When only explicit Context is supported, this parameter
+  SHOULD be required.
+* [Severity Number](./data-model.md#field-severitynumber) (optional)
+* [Severity Text](./data-model.md#field-severitytext) (optional)
+* [Body](./data-model.md#field-body) (optional)
+* [Attributes](./data-model.md#field-attributes) (optional) Event `Attributes` conform
+  to the [standard definition](../common/README.md#standard-attribute) of an attribute.
 
 ## Optional and required parameters
 
@@ -166,22 +196,13 @@ provide it.
 
 ## Concurrency requirements
 
-For languages which support concurrent execution the Logs Bridge APIs provide
+For languages which support concurrent execution the Logs APIs provide
 specific guarantees and safeties.
 
 **LoggerProvider** - all methods are safe to be called concurrently.
 
 **Logger** - all methods are safe to be called concurrently.
 
-## Artifact Naming
-
-The Logs Bridge API is not intended to be called by application developers
-directly, and SHOULD include documentation that discourages direct use. However,
-in the event OpenTelemetry were to add a user facing API, the Logs Bridge API would
-be a natural starting point. Therefore, Log Bridge API artifact, package, and class
-names MUST NOT include the terms "bridge", "appender", or any other qualifier
-that would prevent evolution into a user facing API.
-
 ## References
 
 - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md)

specification/logs/data-model.md

@@ -9,6 +9,7 @@
 
 - [Design Notes](#design-notes)
   * [Requirements](#requirements)
+  * [Events](#events)
   * [Definitions Used in this Document](#definitions-used-in-this-document)
     + [Type `any`](#type-any)
     + [Type `map`](#type-mapstring-any)
@@ -97,6 +98,16 @@ The Data Model aims to successfully represent 3 sorts of logs and events:
   we include in the logs. We can likely modify the source code of the
   application if needed.
 
+### Events
+
+**Status**: [Development](../document-status.md)
+
+Events are OpenTelemetry's standardized format for LogRecords. All semantic
+conventions defined for logs SHOULD be formatted as Events. Requirements and details for the Event format can be found in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md).
+
+Events are intended to be used by OpenTelemetry instrumentation. It is not a
+requirement that all LogRecords are formatted as Events.
+
 ### Definitions Used in this Document
 
 In this document we refer to types `any` and `map<string, any>`, defined as

specification/logs/event-api.md

@@ -34,7 +34,7 @@ The Event API consists of these main components:
 ## Logs API Development
 
 > [!NOTE]
-> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api).
+> We are currently in the process of defining a new [Logs API](./api.md#logs-api).
 
 The intent is that this Logs 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.
 
@@ -66,7 +66,7 @@ both their `Attributes` and their `Body`.
 
 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 Bridge API](./bridge-api.md), instrumentation authors and application
+[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:
 

specification/logs/event-sdk.md

@@ -33,7 +33,7 @@ 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](./bridge-api.md#logs-api).
+> We are currently in the process of defining a new [Logs API](./api.md#logs-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.
 
@@ -91,7 +91,7 @@ Emit a `LogRecord` representing an `Event`.
 **Implementation Requirements:**
 
 The implementation MUST use the parameters
-to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows:
+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
@@ -104,10 +104,10 @@ to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows:
   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](./bridge-api.md#emit-a-logrecord) will
+  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](./bridge-api.md#emit-a-logrecord). If not provided, `Context`
+  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

specification/logs/noop.md

@@ -2,7 +2,7 @@
 linkTitle: No-Op
 --->
 
-# Logs Bridge API No-Op Implementation
+# Logs API No-Op Implementation
 
 **Status**: [Stable](../document-status.md)
 
@@ -23,12 +23,12 @@ linkTitle: No-Op
 Users of OpenTelemetry need a way to disable the API from actually
 performing any operations. The No-Op OpenTelemetry API implementation
 (henceforth referred to as the No-Op) provides users with this
-functionally. It implements the [OpenTelemetry Logs Bridge API](./bridge-api.md)
+functionally. It implements the [OpenTelemetry Logs API](./api.md)
 so that no telemetry is produced and computation resources are minimized.
 
 All language implementations of OpenTelemetry MUST provide a No-Op.
 
-The [Logs Bridge API](./bridge-api.md) defines components with various operations.
+The [Logs API](./api.md) defines components with various operations.
 All No-Op components MUST NOT hold configuration or operational state. All No-op
 operations MUST accept all defined parameters, MUST NOT validate any arguments
 received, and MUST NOT return any non-empty error or log any message.
@@ -42,7 +42,7 @@ provide the same `LoggerProvider` instances to all creation requests.
 
 ### Logger Creation
 
-New `Logger` instances are always created with a [LoggerProvider](./bridge-api.md#loggerprovider).
+New `Logger` instances are always created with a [LoggerProvider](./api.md#loggerprovider).
 Therefore, `LoggerProvider` MUST allow for the creation of `Logger`s.
 All `Logger`s created MUST be an instance of the [No-Op Logger](#logger).
 
@@ -54,4 +54,4 @@ return the same `Logger` instances to all creation requests.
 ### Emit LogRecord
 
 The No-Op `Logger` MUST allow
-for [emitting LogRecords](./bridge-api.md#emit-a-logrecord).
+for [emitting LogRecords](./api.md#emit-a-logrecord).

specification/logs/sdk.md

@@ -60,9 +60,9 @@ The SDK SHOULD allow the creation of multiple independent `LoggerProviders`s.
 ### Logger Creation
 
 It SHOULD only be possible to create `Logger` instances through a `LoggerProvider`
-(see [Bridge API](bridge-api.md)).
+(see [API](api.md)).
 
-The `LoggerProvider` MUST implement the [Get a Logger API](bridge-api.md#get-a-logger).
+The `LoggerProvider` MUST implement the [Get a Logger API](api.md#get-a-logger).
 
 The input provided by the user MUST be used to create
 an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which
@@ -187,7 +187,7 @@ It consists of the following parameters:
   to [No-op Logger](./noop.md#logger).
 
   The value of `disabled` MUST be used to resolve whether a `Logger`
-  is [Enabled](./bridge-api.md#enabled). If `disabled` is `true`, `Enabled`
+  is [Enabled](./api.md#enabled). If `disabled` is `true`, `Enabled`
   returns `false`. If `disabled` is `false`, `Enabled` returns `true`. It is not
   necessary for implementations to ensure that changes to `disabled` are
   immediately visible to callers of `Enabled`. I.e. atomic, volatile,
@@ -208,7 +208,7 @@ associated with the `LogRecord`.
 
 The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from
 the resolved `Context` (either the explicitly passed `Context` or the
-current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord).
+current `Context`) when [emitted](./api.md#emit-a-logrecord).
 
 Counts for attributes due to collection limits MUST be available for exporters
 to report as described in
@@ -312,7 +312,7 @@ components in the SDK:
 
 #### OnEmit
 
-`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-a-logrecord). This
+`OnEmit` is called when a `LogRecord` is [emitted](api.md#emit-a-logrecord). This
 method is called synchronously on the thread that emitted the `LogRecord`,
 therefore it SHOULD NOT block or throw exceptions.
 
@@ -542,6 +542,6 @@ authors MAY decide if they want to make the shutdown timeout configurable.
 ## Logs API
 
 > [!NOTE]
-> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api).
+> We are currently in the process of defining a new [Logs API](./api.md#logs-api).
 
 - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md)