Add prototyping requirement for significant changes (#2502)

Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
This commit is contained in:
Liudmila Molkova 2025-07-14 08:13:25 -07:00 committed by GitHub
parent 32ad8388cf
commit ee299e5c42
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 15 additions and 2 deletions

View File

@ -11,4 +11,4 @@ Note: if the PR is touching an area that is not listed in the [existing areas](h
* [ ] [CONTRIBUTING.md](https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md) guidelines followed.
* [ ] Change log entry added, according to the guidelines in [When to add a changelog entry](https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md#when-to-add-a-changelog-entry).
* If your PR does not need a change log, start the PR title with `[chore]`
* [ ] Links to the prototypes or existing instrumentations (when adding or changing conventions)

View File

@ -52,6 +52,7 @@ Agreement](https://identity.linuxfoundation.org/projects/cncf).
When contributing to semantic conventions, it's important to understand a few
key, but non-obvious, aspects:
- In the PR description, include links to the relevant instrumentation and any applicable prototypes. Non-trivial changes to semantic conventions should be prototyped in the corresponding instrumentation(s).
- All attributes, metrics, etc. are formally defined in YAML files under
the `model/` directory.
- All descriptions, normative language are defined in the `docs/` directory.

View File

@ -10,6 +10,7 @@ linkTitle: How to define new semantic conventions
- [Defining new conventions](#defining-new-conventions)
- [Best practices](#best-practices)
- [Prototyping](#prototyping)
- [Defining attributes](#defining-attributes)
- [Defining spans](#defining-spans)
- [Defining metrics](#defining-metrics)
@ -37,6 +38,18 @@ for new areas or make substantial changes to the existing ones.
>
> This section contains non-normative guidance.
#### Prototyping
It is strongly recommended to prototype proposed conventions in one or more instrumentations and:
- validate the feasibility of collecting the proposed telemetry and attributes, ensuring the information is available and can be gathered with reasonable overhead,
- confirm that the proposed terminology applies across the diverse libraries and technologies covered by the conventions,
- provide actionable guidance to instrumentation authors on when and how to collect attributes and record telemetry,
- evaluate how the new or updated telemetry integrates with other instrumentation layers, identifying gaps, duplication, or opportunities to improve the end-user experience.
#### Defining attributes
Reuse existing attributes when possible. Look through [existing conventions](/docs/registry/attributes/) for similar areas,
@ -156,7 +169,6 @@ TBD
TODO:
- prototyping/implementation requirements
- migration plan
### Migration plan