Add prototyping requirement for significant changes (#2502)
Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com>
This commit is contained in:
parent
32ad8388cf
commit
ee299e5c42
|
|
@ -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.
|
* [ ] [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).
|
* [ ] 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]`
|
* 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)
|
||||||
|
|
|
||||||
|
|
@ -52,6 +52,7 @@ Agreement](https://identity.linuxfoundation.org/projects/cncf).
|
||||||
When contributing to semantic conventions, it's important to understand a few
|
When contributing to semantic conventions, it's important to understand a few
|
||||||
key, but non-obvious, aspects:
|
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
|
- All attributes, metrics, etc. are formally defined in YAML files under
|
||||||
the `model/` directory.
|
the `model/` directory.
|
||||||
- All descriptions, normative language are defined in the `docs/` directory.
|
- All descriptions, normative language are defined in the `docs/` directory.
|
||||||
|
|
|
||||||
|
|
@ -10,6 +10,7 @@ linkTitle: How to define new semantic conventions
|
||||||
|
|
||||||
- [Defining new conventions](#defining-new-conventions)
|
- [Defining new conventions](#defining-new-conventions)
|
||||||
- [Best practices](#best-practices)
|
- [Best practices](#best-practices)
|
||||||
|
- [Prototyping](#prototyping)
|
||||||
- [Defining attributes](#defining-attributes)
|
- [Defining attributes](#defining-attributes)
|
||||||
- [Defining spans](#defining-spans)
|
- [Defining spans](#defining-spans)
|
||||||
- [Defining metrics](#defining-metrics)
|
- [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.
|
> 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
|
#### Defining attributes
|
||||||
|
|
||||||
Reuse existing attributes when possible. Look through [existing conventions](/docs/registry/attributes/) for similar areas,
|
Reuse existing attributes when possible. Look through [existing conventions](/docs/registry/attributes/) for similar areas,
|
||||||
|
|
@ -156,7 +169,6 @@ TBD
|
||||||
|
|
||||||
TODO:
|
TODO:
|
||||||
|
|
||||||
- prototyping/implementation requirements
|
|
||||||
- migration plan
|
- migration plan
|
||||||
|
|
||||||
### Migration plan
|
### Migration plan
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue