Define Event API arguments and mapping to log record

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,10 @@ 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` and `domain`.
 Within a particular `domain`, the `name` uniquely defines a particular class or
-type of event. Events with the same `domain` / `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).
+type of event. Events with the same `domain` / `name` 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
@@ -76,19 +78,56 @@ 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.
+* 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 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 `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`.
+  when [creating the EventLogger](#create-eventlogger) MUST be used to set
+  the `event.domain` [attribute](./data-model.md#field-attributes). The
+  implementation MUST ensure that the `event_domain` takes precedence over any
+  additional `Attributes` recorded with the Event.
+* 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 `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.