First stab at documenting the art of defining semantic conventions #1707
Conversation
Copilot
AI
left a comment
Copilot
AI
left a comment
There was a problem hiding this comment.
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Comments suppressed due to low confidence (1)
docs/general/how-to-define-semantic-conventions.md:69
- The phrase 'are involved into instrumentation efforts' should be 'are involved in instrumentation efforts'.
are involved into instrumentation efforts, and are committed to be the point of contact for
| <!-- tocstop --> | ||
|
|
||
| This document describes requirements, recommendations, and best practices on how to define conventions | ||
| for the new areas or make substantial changes to the existing ones. |
There was a problem hiding this comment.
| for the new areas or make substantial changes to the existing ones. | |
| for new areas or make substantial changes to the existing ones. |
|
|
||
| - New conventions MUST have a group of codeowners. See [project management](https://github.com/open-telemetry/community/blob/main/project-management.md) for more details. | ||
| <!-- TODO: add CI check for CODEOWNERS file (when a new area is added) --> | ||
| - New conventions SHOULD be defined in YAML files. See [YAML Model for Semantic Conventions](/model/README.md) for the details. |
There was a problem hiding this comment.
With this SHOULD I assume your intention is that things should be added to yaml files where possible, but also it's OK to add conventions as just text in markdown files? For example how to record span names?
If this is right, maybe we can say something like this, to make it more clear?
- New conventions MUST be defined in YAML files. Conventions that cannot be recorded as part of the YAML model MAY be added in the corresponding markdown file (e.g., conventions for span name)
| check out [common attributes](/docs/general/attributes.md). | ||
| Semantic conventions authors are encouraged to use attributes from different namespaces. | ||
|
|
||
| Introduce new attributes when there is a clear use-case for them. Consider adding |
There was a problem hiding this comment.
I guess we can make this shorter with just:
| Introduce new attributes when there is a clear use-case for them. Consider adding | |
| Consider adding new attributes when the following apply: |
| them if most of the following apply: | ||
|
|
||
| - They provide a clear benefit to end users by enhancing telemetry. | ||
| - You plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. |
There was a problem hiding this comment.
| - You plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. | |
| - There is a clear plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. |
I'm never sure if we should avoid using "you" in conventions 🤔
|
|
||
| - They provide a clear benefit to end users by enhancing telemetry. | ||
| - You plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. | ||
| - The attribute will be utilized in instrumentations. |
There was a problem hiding this comment.
| - The attribute will be utilized in instrumentations. | |
| - The attribute will be utilized in instrumentations. |
If the above is true, isn't this already somewhat implicit? (that they are used in spans/metrics/logs etc?
I think what we have been trying to push when folks want to add new things, is that we'd like to see implementations of them, so maybe we can also say:
- There is a clear plan on how these attributes will be used by instrumentations
| - You plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. | ||
| - The attribute will be utilized in instrumentations. | ||
|
|
||
| Postpone adding new attributes if their benefit to telemetry is not yet clear. |
There was a problem hiding this comment.
Maybe here we can say something like this instead?
Semantic convention mantainers may reject the addition of new attributes if their benefit/usecase is not yet clear.
| ### Suggesting conventions for a new areas | ||
|
|
||
| Defining semantic conventions involves a group of people who are familiar with the domain, | ||
| are involved into instrumentation efforts, and are committed to be the point of contact for |
There was a problem hiding this comment.
| are involved into instrumentation efforts, and are committed to be the point of contact for | |
| are involved with instrumentation efforts, and are committed to be the point of contact for |
| Check out [project management](https://github.com/open-telemetry/community/blob/main/project-management.md) | ||
| for the details on how to start. | ||
|
|
||
| Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) for |
There was a problem hiding this comment.
| Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) for | |
| Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) document for |
A lot of todos, which I'd like to tackle in follow up PRs (hopefully with the help of others)
Merge requirement checklist
[chore]