Define Event API arguments and mapping to log record #3772
Conversation
Why 10? Are we trying to be in the middle of the "info" range for some reason? Note that mappings of other formats to Otel use INFO=9 as the level for informational events. Should we use the same level for Otel-generated events? I agree with all other assertions in the PR description. |
We discussed that a good default severity would be an "info" level, but I took some agency with the selection of 10 to stay in the middle of the info range. I don't feel strongly about this though and the appendix you point to seems to be a pretty good reason to select INFO=9 as the default. |
|
Draft PR where I've prototyped these changes in opentelemetry-java: open-telemetry/opentelemetry-java#6001 |
|
Event domain and name are now merged, I think this needs to be updated to reflect that (or a separate is needed to do just that). |
…y-specification into event-api-args
|
I've rebased this now that event domain and name are merged in #3749. |
|
@jack-berg CHANGELOG entry? |
|
Changelog entry added @carlosalberto 👍 |
|
Will merge tomorrow if there are no additional comments. |
…3772) In the 11/17/23 Event SIG we discussed and reached agreement on a number of things related to the Event API and how its parameters should manifest on resulting log record: - Some, but not all the parameters of [emit a logRecord](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/bridge-api.md#emit-a-logrecord) should be exposed in the Event API - [LogRecord#SeverityText](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-severitytext) should not be exposed as an Event API parameter. The SeverityText is used to record the original severity as recorded in the original log framework. The Event API is not for bridging log frameworks and this this field does not make sense to expose. The Event API implementation should leave SeverityText blank. - [LogRecord#ObservedTimestamp](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-observedtimestamp) should not be as exposed as an Event API parameter. The semantics of ObservedTimestamp are defined as "Time when the event was observed by the collection system". For the Event API, the ObserveTimestamp is always when the Event is emitted. - The Event Payload, which conforms to the well defined schema for a particular `event.name` (event.domain is going away in open-telemetry#3749) should be an [AnyValue](https://github.com/open-telemetry/opentelemetry-proto/blob/ea449ae0e9b282f96ec12a09e796dbb3d390ed4f/opentelemetry/proto/common/v1/common.proto#L28) and recorded to the log record body. - We need some way to sample / filter Events based on the notion of priority / severity. We decided to use the [LogRecord#SeverityNumber](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-severitynumber) field for this purpose rather than introducing a new concept. LogRecord#SeverityNumber is optional, and we want the equivalent Event API parameter to be optional as well. Therefore, I've indicated that Event API implementations should set a default SeverityNumber of 10. Without choosing a default, future sampling strategies that are based on SeverityNumber will filter away all Events which do not explicitly set a SeverityNumber, which is not desirable. Note that there is going to be a corresponding PR in `semantic-conventions` which says that Events put their payload in the LogRecord#Body field. --------- Co-authored-by: Carlos Alberto Cortez <[email protected]> Co-authored-by: Armin Ruech <[email protected]>
"merge conflict" between open-telemetry#3749 and open-telemetry#3772.
In the 11/17/23 Event SIG we discussed and reached agreement on a number of things related to the Event API and how its parameters should manifest on resulting log record:
event.name(event.domain is going away in Merge event's domain and name #3749) should be an AnyValue and recorded to the log record body.Note that there is going to be a corresponding PR in
semantic-conventionswhich says that Events put their payload in the LogRecord#Body field.