diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 0d8fe5fe5..efcdf5315 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11ef057d1..58deb0779 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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. diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index 8be86c4c6..af33d0c42 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -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