Skip to content

Conversation

@pellared
Copy link
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
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

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

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
@pellared pellared requested a review from lmolkova November 5, 2025 15:20
Copy link
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

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
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: In progress
Status: Ready to be Merged

Development

Successfully merging this pull request may close these issues.

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

4 participants