First stab at documenting the art of defining semantic conventions

[lmolkova]

A lot of todos, which I'd like to tackle in follow up PRs (hopefully with the help of others)

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• schema-next.yaml updated with changes to existing conventions.

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

[joaopgrassi]

This is a great start!

[joaopgrassi]

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)

[lmolkova]

I want to put MUST here, but there are plenty of cases where we can't. Span names is a good example, but we have other things we can't yet express: references to metrics, complex attribute types, resources that are expected to be associated with telemetry, etc.

I use SHOULD for new conventions and MUST as a prereq to stabilization.
I feel REQUIRING yaml for experimental stuff is not necessary, but also, it feels wrong to require something none of the conventions fully implement.

Maybe once the tooling covers 90% of scenarios we can revisit it and be more strict?

[joaopgrassi]

Suggested change

	- 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 🤔

[joaopgrassi]

Suggested change

	- 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

[lmolkova]

If the above is true, isn't this already somewhat implicit? (that they are used in spans/metrics/logs etc?

I'd like to avoid someone defining conventions without planning to actually implement it. Changed the wording slightly to make it more clear. LMK what you think!

Also, some of the attributes are not really part of any specific telemetry signal. E.g. code, thread, enduser, session - it's something you stamp on any span/log/etc to enrich it. For those we'd probably not require referencing them on a span/metric/etc, but would ask about instrumentations and some plaintext description of how they are used.

There is a clear plan on how these attributes will be used by instrumentations

I like this, thanks!

[braydonk]

Minor grammar feedback