Event payload lives in the LogRecord body

[breedx-splk]

Changes

In the Events Working Group on 2023-11-17, we decided that the Event payload will exist in the Body of the LogRecord. This provides that clarity and also provides some additional descriptive wording about what an event is.

This also relates to open-telemetry/opentelemetry-specification#3772

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• CHANGELOG.md updated for non-trivial changes.
• schema-next.yaml updated with changes to existing conventions.

[trask]

Should this be in the spec (vs semconv)?

nm, I see it's already in the spec: https://github.com/open-telemetry/opentelemetry-specification/blob/703a0af47acac67775f42b9c86570eebb9283b21/specification/logs/event-api.md?plain=1#L98-L100

[trask]

Adding reason for my approval:

Putting the payload in the LogRecord body makes a clear delineation between

• attributes (metadata), and
• body (payload)

(ok, it's still a bit messy whether some fields should go in payload or metadata, but I think that discussion can happen when we start adding semantic conventions for specific events).

Further (and importantly), we can then restrict the Event API to only support non-nested attributes, which allows us to bypass the can of worms in open-telemetry/opentelemetry-specification#2888

[yurishkuro]

The Event API already says that payload is placed in the body. It also says event may have attributes. Neither the spec nor this PR specify what a "payload" is.

[lmolkova]

I'd like to see a story for span events. It can look as simple as:

• define event.payload attribute (for event semconv type which is span event) - this is a plain string
• define other similar attributes for properties that Event has but span event doesn't (seem to be SeverityNumber only)

Then semconv authors would be able to describe simple events using schemas/mds the moment this PR is merged.
Exporters could start translating span events to events if they want to.

Events WG can keep working on defining the future of Event/Log semconv in parallel.
event.payload and any other mapping attributes can stay experimental forever and can be removed after the future is defined.

Span events would never be good enough to describe complicated structured events, and for this we can always refer developers to Events/Logs. But simple back-compat story is necessary anyway.

Update:
as an alternative to supporting span-events, I'd love to see current event type repurposed to log events with a way to specify all Event properties and have an example of how to represent a simple blob-of-text payload in semconv.

[breedx-splk]

I'd like to see a story for span events.

Thanks @lmolkova. A while back, @jsuereth also brought up span events as a potential point of confusion.

Did you see Trask's comment up there? This page is intended only to describe stand-alone events, and makes no reference to Spans anywhere. The only reasonable way I could understand a user being confused between events and span events is if they came from a tracing background and just ignored the fact that span events have the word span in them. :)

Do we really think this is a blocker for this PR, or is it something we can work on after to unify/clarify the relationship between events and span events in follow-up work?

[trask]

The only reasonable way I could understand a user being confused between events and span events is if they came from a tracing background and just ignored the fact that span events have the word span in them. :)

I think users will definitely be confused between events and span events 😅. We could probably continue discussing that in open-telemetry/opentelemetry-specification#3406, but maybe in the short-term (this PR), we could update the page title here from "Semantic Conventions for Events" to "Semantic Conventions for (log-based) Events"?

[breedx-splk]

@jsuereth As requested, I have opened #695 to help track/discuss the span event vs. standalone event distinction. 🙏🏻 Thanks thanks.

[breedx-splk]

Adding purely informative link to related spec PR.