Skip to content

[events] refine general event semantics documentation#3030

Merged
lmolkova merged 10 commits intoopen-telemetry:mainfrom
pellared:evt-refine
Nov 20, 2025
Merged

[events] refine general event semantics documentation#3030
lmolkova merged 10 commits intoopen-telemetry:mainfrom
pellared:evt-refine

Conversation

@pellared
Copy link
Copy Markdown
Member

@pellared pellared commented Nov 4, 2025

Towards stabilization of https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md

Fixes #1651

Changes

This PR refines the documentation for general event semantics to improve clarity and structure.

Documentation improvements

  • Restructure event semantics section for better readability
  • Consolidate event name definition with its uniquely identifying role
  • Simplify cardinality and naming guidelines into single concise statement

Requirement level clarifications

  • Attributes: Strengthen from MAY to SHOULD to emphasize their importance for providing event context
  • Severity number: Strengthen from MAY to SHOULD to encourage consistent severity tracking
  • Remove explicit "body MAY be present" statement (still implied in first bullet) given unclear use cases. Body SHOULD NOT be used.

Technical changes

  • Consistent hyperlinking to all specification fields (event name, attributes, body, severity number)
  • Align with RFC 2119 keyword usage patterns (use SHOULD instead of RECOMMENDED)
  • Improve consistency with naming guidelines reference
  • Enhanced external event compatibility guidance with explicit instrumentation SHOULD

Rationale

The changes improve developer experience by:

  1. Making requirements clearer and easier to scan
  2. Emphasizing best practices (using attributes and severity numbers)
  3. Reducing redundancy while maintaining completeness
  4. Better aligning with the structure used in other semantic convention documents
  5. Providing more concise and actionable guidance for convention authors

@pellared pellared added the Skip Changelog Label to skip the changelog check label Nov 4, 2025
@pellared
Copy link
Copy Markdown
Member Author

pellared commented Nov 4, 2025

I do not think this needs a changelog. Feel free to remove the label if you disagree.

@pellared pellared marked this pull request as ready for review November 4, 2025 11:39
@pellared pellared requested review from a team as code owners November 4, 2025 11:39
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR refines the documentation for OpenTelemetry Events to improve clarity and better align with semantic conventions standards. The changes reorganize and consolidate event requirements while maintaining technical accuracy.

  • Consolidated event definition requirements into a clearer structure
  • Improved the phrasing of event semantics to be more concise and consistent with RFC 2119 keywords
  • Enhanced guidance for external event compatibility scenarios

Comment thread docs/general/events.md Outdated
Clarified guidelines on event details and body usage.
@pellared pellared added this to Logs SIG Nov 4, 2025
@pellared pellared moved this to In progress in Logs SIG Nov 4, 2025
@pellared pellared self-assigned this Nov 4, 2025
@pellared pellared requested a review from lmolkova November 4, 2025 20:30
Comment thread docs/general/events.md Outdated
@pellared pellared requested a review from lmolkova November 5, 2025 15:20
Comment thread docs/general/events.md Outdated
Comment thread docs/general/events.md Outdated
Comment thread docs/general/events.md Outdated
Copy link
Copy Markdown
Member

@lmolkova lmolkova left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

didn't realize I had pending comments, posing now

Comment thread docs/general/events.md Outdated
Removed redundant phrases and clarified semantic conventions for events.
@pellared pellared requested a review from lmolkova November 18, 2025 19:10
@pellared pellared requested a review from cijothomas November 18, 2025 19:10
@github-project-automation github-project-automation Bot moved this from Untriaged to Needs More Approval in Semantic Conventions Triage Nov 19, 2025
@lmolkova lmolkova moved this from Needs More Approval to Ready to be Merged in Semantic Conventions Triage Nov 19, 2025
@github-project-automation github-project-automation Bot moved this from Ready to be Merged to Needs More Approval in Semantic Conventions Triage Nov 19, 2025
@lmolkova lmolkova moved this from Needs More Approval to Ready to be Merged in Semantic Conventions Triage Nov 19, 2025
@lmolkova lmolkova added this pull request to the merge queue Nov 20, 2025
Merged via the queue into open-telemetry:main with commit 4100747 Nov 20, 2025
15 checks passed
@github-project-automation github-project-automation Bot moved this from In progress to Done in Logs SIG Nov 20, 2025
bachgarash pushed a commit to bachgarash/semantic-conventions that referenced this pull request Nov 28, 2025
jsuereth pushed a commit to jsuereth/semantic-conventions that referenced this pull request Dec 2, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:event Skip Changelog Label to skip the changelog check

Projects

Status: Done
Archived in project

Development

Successfully merging this pull request may close these issues.

Logs/Events guidance on what to put to attributes vs body

5 participants