[Discussion] How should events be represented in semantic conventions (one per file or one per namespace)

[MSNev]

Area(s)

area:event

Is your change request related to a problem? Please describe.

Description

This issue is a discussion into how should events be described within semantic conventions, there are several options

• One event per event (the client / event preference), but will require additional naming
• One file per namespace, eg all "browser" events should be within the same file
• Leave it up to the event domain as it might depend.

We currently have a mixture with the following 2 PR's open which are showing the basic 2 options

• Single file per namespace: Add browser events and describe their payload by scheler · Pull Request #838 · open-telemetry/semantic-conventions (github.com)
• Single file for event: Update the device.app.lifecycle event description and constraints by MSNev · Pull Request #794 · open-telemetry/semantic-conventions (github.com)

Describe the solution you'd like

One per file

When using one event per file we should have some file / folder naming conventions to avoid accidentally creating duplicate events with the same name but located in different sections / files of semantic conventions.

Proposals

Note: the <domain> is the "area" where the events is created / generated and will most likely be related to the namespace of the event.

• have a folder structure with the namespace

  • docs/<domain>/the/namespace/eventname.md
  • docs/<domain>/the.namespace/eventname.md
  • docs/events/the/namespace/eventname.md
  • docs/events/the.namespace/eventname.md

• have the filename be full qualified

  • docs/<domain>/the,namespace.eventname.md
  • docs/events/the,namespace.eventname.md

Questions

• Should the events be "grouped" together (a single events folder) or by domain mobile / browser

One file per namespace

This enables all related events to be grouped together and leaves the naming so all events are in a single file events.md

Proposals

Note: the <domain> is the "area" where the events is created / generated and will most likely be related to the namespace of the event. (mobile, browser)

• have a folder structure with the namespace
  • docs/<domain>/events.md

One possible downside of this approach is that when / if events become generic they will completely change their location.

Describe alternatives you've considered

No response

Additional context

No response

[MSNev]

Basic Voting Emoji's

👍 - Require a single file per event
🚀 - Require Single file per domain (all events of a namespace / domain should be in a single file events.md)
👀 - Leave it up to the event domain as it will depend (defer the discussion)

[MSNev]

Where should the events be located in
👍 - a single location docs/events (docs/events/<domain>)
👀 - a location based on the event domain (/docs/mobile/, /docs/browser/, /docs/xxxxx/ )
☹️ - no preference, just don't clash with existing folders

[MSNev]

Other options for the above exist as well, so please provide other preferences if you have them.

[lquerel]

In the "one file per namespace" section
One possible downside of this approach is that when / if events become generic they will completely change their location.

How does this not affect the proposal of one event per file? I don't really see any difference in this aspect between the two approaches.

[lmolkova]

Event definition is part of some other domain. E.g. we're going to define a bunch of events for LLM.
LLM events should be defined somewhere next to LLM spans and metrics, maybe even in the same file.

So my strong preference is on

👀 - Leave it up to the event domain as it will depend

or

👀 - a location based on the event domain

which seem like the same option.

[lmolkova]

Fixed in #1345