Split out Event API from Log API (open-telemetry#2941)

Resolves open-telemetry#2917.

Depends on open-telemetry#2940.

Author: jack-berg

CHANGELOG.md

@@ -18,6 +18,8 @@ release.
 - Move `event.domain` from InstrumentationScope attributes to LogRecord
   attributes.
   ([#2940](https://github.com/open-telemetry/opentelemetry-specification/pull/2940))
+- Split out Event API from Log API
+  ([#2941](https://github.com/open-telemetry/opentelemetry-specification/pull/2941))
 
 ### Resource
 

specification/logs/README.md

@@ -157,8 +157,10 @@ Given the above state of the logging space we took the following approach:
   features than what is defined in OpenTelemetry. It is NOT a goal of
   OpenTelemetry to ship a feature-rich logging library.
 
-- OpenTelemetry defines an API for [emitting Events](./api.md#emit-event).
-  Application developers are encouraged to call this API directly.
+- OpenTelemetry defines an API for [emitting Events](./event-api.md). The API
+  consists of convenience methods which delegate to the API
+  for [emitting LogRecords](./api.md#emit-logrecord). Application developers are
+  encouraged to call this API directly.
 
 - OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md),
   which enables configuration of [processing](./sdk.md#logrecordprocessor)

specification/logs/api.md

@@ -1,4 +1,4 @@
-# Events and Logs API Interface
+# Logs API Interface
 
 **Status**: [Experimental](../document-status.md)
 
@@ -14,7 +14,6 @@
     + [Get a Logger](#get-a-logger)
 - [Logger](#logger)
   * [Logger operations](#logger-operations)
-    + [Emit Event](#emit-event)
     + [Emit LogRecord](#emit-logrecord)
 - [LogRecord](#logrecord)
 - [Usage](#usage)
@@ -26,20 +25,19 @@
 
 </details>
 
-The Events and Logs API consist of these main classes:
+The Logs API consist of these main classes:
 
 * LoggerProvider is the entry point of the API. It provides access to Loggers.
 * Logger is the class responsible for
-  creating [Events](./semantic_conventions/events.md)
-  and [Logs](./data-model.md#log-and-event-record-definition) as LogRecords.
+  emitting [Logs](./data-model.md#log-and-event-record-definition) as
+  LogRecords.
 
 LoggerProvider/Logger are analogous to TracerProvider/Tracer.
 
 ```mermaid
 graph TD
     A[LoggerProvider] -->|Get| B(Logger)
-    B --> C(Event)
-    B --> D(Log)
+    B --> C(Log)
 ```
 
 ## LoggerProvider
@@ -91,12 +89,9 @@ produced by this library.
 the scope has a version (e.g. a library version). Example value: 1.0.0.
 - `schema_url` (optional): Specifies the Schema URL that should be recorded in
 the emitted telemetry.
-- `event_domain` (optional): Specifies the domain for the Events emitted, which
-  MUST be added as an attribute with the key `event.domain`
-  to [emitted Events](#emit-event).
 - `include_trace_context` (optional): Specifies whether the Trace Context should
-automatically be passed on to the Events and Logs emitted by the Logger. This
-SHOULD be true by default.
+  automatically be passed on to the LogRecords emitted by the Logger. This
+  SHOULD be true by default.
 - `attributes` (optional): Specifies the instrumentation scope attributes to
 associate with emitted telemetry.
 
@@ -111,7 +106,7 @@ identifying fields are equal. The term *distinct* applied to Loggers describes
 instances where at least one identifying field has a different value.
 
 Implementations MUST NOT require users to repeatedly obtain a Logger again with
-the same name+version+schema_url+event_domain+include_trace_context+attributes
+the same name+version+schema_url+include_trace_context+attributes
 to pick up configuration changes. This can be achieved either by allowing to
 work with an outdated configuration or by ensuring that new configuration
 applies also to previously returned Loggers.
@@ -120,7 +115,7 @@ Note: This could, for example, be implemented by storing any mutable
 configuration in the `LoggerProvider` and having `Logger` implementation objects
 have a reference to the `LoggerProvider` from which they were obtained.
 If configuration must be stored per-Logger (such as disabling a certain `Logger`),
-the `Logger` could, for example, do a look-up with its name+version+schema_url+event_domain+include_trace_context+attributes
+the `Logger` could, for example, do a look-up with its name+version+schema_url+include_trace_context+attributes
 in a map in the `LoggerProvider`, or the `LoggerProvider` could maintain a registry
 of all returned `Logger`s and actively update their configuration if it changes.
 
@@ -130,7 +125,7 @@ the emitted data format is capable of representing such association.
 
 ## Logger
 
-The `Logger` is responsible for emitting Events and Logs.
+The `Logger` is responsible for emitting `LogRecord`s
 
 Note that `Logger`s should not be responsible for configuration. This should be
 the responsibility of the `LoggerProvider` instead.
@@ -139,24 +134,6 @@ the responsibility of the `LoggerProvider` instead.
 
 The Logger MUST provide functions to:
 
-#### Emit Event
-
-Emit a `LogRecord` representing an Event to the processing pipeline.
-
-This function MAY be named `logEvent`.
-
-**Parameters:**
-
-* `name` - the Event name. This argument MUST be recorded as a `LogRecord`
-  attribute with the key `event.name`. Care MUST be taken by the implementation
-  to not override or delete this attribute while the Event is emitted to
-  preserve its identity.
-* `logRecord` - the [LogRecord](#logrecord) representing the Event.
-
-Events require the `event.domain` attribute. The API MUST not allow creating an
-Event if `event_domain` was not specified when
-the [Logger was obtained](#get-a-logger).
-
 #### Emit LogRecord
 
 Emit a `LogRecord` to the processing pipeline.
@@ -173,7 +150,7 @@ by end users or other instrumentation.
 
 ## LogRecord
 
-The API emits [Events](#emit-event) and [LogRecords](#emit-logrecord) using
+The API emits [LogRecords](#emit-logrecord) using
 the `LogRecord` [data model](data-model.md).
 
 A function receiving this as an argument MUST be able to set the following

specification/logs/event-api.md

@@ -0,0 +1,69 @@
+# Events API Interface
+
+**Status**: [Experimental](../document-status.md)
+
+<details>
+<summary>Table of Contents</summary>
+
+<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
+
+<!-- toc -->
+
+- [EventLogger](#eventlogger)
+  * [EventLogger Operations](#eventlogger-operations)
+    + [Create EventLogger](#create-eventlogger)
+    + [Emit Event](#emit-event)
+
+<!-- tocstop -->
+
+</details>
+
+The Event API offers convenience methods
+for [emitting LogRecords](./api.md#emit-logrecord) that conform
+to the [semantic conventions for Events](./semantic_conventions/events.md).
+
+## EventLogger
+
+The `EventLogger` is the entrypoint of the Event API, and is responsible for
+emitting `Events` as `LogRecords`.
+
+### EventLogger Operations
+
+The `EventLogger` MUST provide functions to:
+
+#### Create EventLogger
+
+New `EventLogger` instances are created though a constructor or factory method
+on `EventLogger`.
+
+**Parameters:**
+
+* `logger` - the delegate [Logger](./api.md#logger) used to emit `Events`
+  as `LogRecords`.
+* `event_domain` - the domain of emitted events, used to set the `event.domain`
+  attribute.
+
+#### Emit Event
+
+Emit a `LogRecord` representing an `Event` to the delegate `Logger`.
+
+This function MAY be named `logEvent`.
+
+**Parameters:**
+
+* `event_name` - the Event name. This argument MUST be recorded as a `LogRecord`
+  attribute with the key `event.name`. Care MUST be taken by the implementation
+  to not override or delete this attribute while the Event is emitted to
+  preserve its identity.
+* `logRecord` - the [LogRecord](./api.md#logrecord) representing the Event.
+
+**Implementation Requirements:**
+
+The implementation MUST [emit](./api.md#emit-logrecord) the `logRecord` to
+the `logger` specified when [creating the EventLogger](#create-eventlogger)
+after making the following changes:
+
+* The `event_domain` specified
+  when [creating the EventLogger](#create-eventlogger) MUST be set as
+  the `event.domain` attribute on the `logRecord`.
+* The `event_name` MUST be set as the `event.name` attribute on the `logRecord`.

specification/logs/img/application-api-sdk.png

@@ -3,8 +3,8 @@
 **Status**: [Experimental](../../document-status.md)
 
 This document defines semantic conventions for recording exceptions on
-[logs](../api.md#emit-logrecord) and [events](../api.md#emit-event) emitted
-through the [Logger API](../api.md#logger).
+[logs](../api.md#emit-logrecord) and [events](../event-api.md#emit-event)
+emitted through the [Logger API](../api.md#logger).
 
 <!-- toc -->