Define Event API arguments and mapping to log record

CHANGELOG.md

@@ -25,6 +25,10 @@ release.
   ([#3741](https://github.com/open-telemetry/opentelemetry-specification/pull/3741))
 - BREAKING: Change `event.name` definition to include `namespace` and removed `event.domain` from log event attributes.
   ([#3749](https://github.com/open-telemetry/opentelemetry-specification/pull/3749))
+- BREAKING: Refine the arguments of the emit Event API. Instead of accepting
+  a `LogRecord`, the individual arguments are enumerated along with the
+  implementation requirements on how those arguments map to `LogRecord`.
+  ([#3772](https://github.com/open-telemetry/opentelemetry-specification/pull/3772))
 
 ### Resource
 

specification/logs/event-api.md

@@ -14,6 +14,7 @@
   * [EventLogger Operations](#eventlogger-operations)
     + [Create EventLogger](#create-eventlogger)
     + [Emit Event](#emit-event)
+- [Optional and required parameters](#optional-and-required-parameters)
 
 <!-- tocstop -->
 
@@ -32,9 +33,9 @@ using the same [data model](./data-model.md).
 However, OpenTelemetry does recognize a subtle semantic difference between
 LogRecords and Events: Events are LogRecords which have a `name` which uniquely
 defines a particular class or type of event. All events with the same `name`
-follow the same schema which assists in analysis in observability platforms.
-Events are described in more detail in the
-[semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md).
+have `Payloads` that conform to the same schema, which assists in analysis in
+observability platforms. Events are described in more detail in
+the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md).
 
 While the logging space has a diverse legacy with many existing logging
 libraries in different languages, there is not ubiquitous alignment with
@@ -74,17 +75,55 @@ 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](./data-model.md#log-and-event-record-definition) representing
-  the Event.
+* The `Name` of the Event, as described
+  in [event.name semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md).
+* The (`AnyValue`) (optional) `Payload` of the Event.
+* The `Timestamp` (optional) of the Event.
+* The [Context](../context/README.md) (optional) associated with the Event.
+* The `SeverityNumber` (optional) of the Event.
+* The `Attributes` (optional) of the Event. Event `Attributes` provide
+  additional details about the Event which are not part of the
+  well-defined `Payload`.
 
 **Implementation Requirements:**
 
-The implementation MUST [emit](./bridge-api.md#emit-a-logrecord) the `logRecord` to
-the `logger` specified when [creating the EventLogger](#create-eventlogger)
-after making the following changes:
-
-* The `event_name` MUST be set as the `event.name` attribute on the `logRecord`.
+The implementation MUST use the parameters
+to [emit a logRecord](./bridge-api.md#emit-a-logrecord) using the `logger`
+specified when [creating the EventLogger](#create-eventlogger) as follows:
+
+* The `Name` MUST be used to set
+  the `event.name` [Attribute](./data-model.md#field-attributes). If
+  the `Attributes` provided by the user contain an `event.name` attribute the
+  value provided in the `Name` takes precedence.
+* If provided by the user, the `Payload` MUST be used to set
+  the [Body](./data-model.md#field-body). If not provided, `Body` MUST not be
+  set.
+* If provided by the user, the `Timestamp` MUST be used to set
+  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 `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`
+  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
+  logRecord. If not provided, `SeverityNumber` MUST be set
+  to `SEVERITY_NUMBER_INFO=9`.
+* The [Severity Text](./data-model.md#field-severitytext) MUST not be set.
+* If provided by the user, the `Attributes` MUST be used to set
+  the [Attributes](./data-model.md#field-attributes). The user
+  provided `Attributes` MUST not take over the `event.domain` and `event.name`
+  attributes previously discussed.
+
+## Optional and required parameters
+
+The operations defined include various parameters, some of which are marked
+optional. Parameters not marked optional are required.
+
+For each optional parameter, the API MUST be structured to accept it, but MUST
+NOT obligate a user to provide it.
+
+For each required parameter, the API MUST be structured to obligate a user to
+provide it.