Document that OpenTelemetry instrumentation should follow semantic conventions

[jack-berg]

I don't think we explicitly say this anywhere but instrumentation that is hosted by / maintained in the OpenTelemetry org should follow the semantic conventions. Perhaps this is implicit / obvious, but I think it would be good to add normative language to the spec which makes this clear.

Some other thoughts on the subject:

• Long term there will be an increasing amount of instrumentation embedded directly in libraries. We can't force library authors to follow the conventions, but we should set an example in the instrumentation we do write.
• This would relieve instrumentation authors of having to duplicate the decision making process of whether a particular change the semantic convention is good. If its in the convention, embody it in the instrumentation. If you disagree with the convention, go engage with the semantic convention group.
• The semantic conventions are in varying states of maturity, and there is a lot of instrumentation out there. Its not realistic (or necessarily desirable) to keep all instrumentation up to date with a semantic convention domain experiencing high churn. So there will be some grey area on when its appropriate to reflect some change to the semantic conventions in instrumentation. But the goal should ultimately be to align instrumentation and semantic conventions, especially as the conventions approach / become stable.

[dyladan]

In principle I agree with this, but I also think instrumentation authors are an important feedback mechanism for the semconv, even after the semconv is written. I think we should distinguish between experimental and stable semconv in this area. Experimental semconv is just that: experimental, and should be treated as such during the implementation phase. Taking the recent case of the JS lambda instrumentation, the experimental spec was updated in such a way that it broke a subset of existing users. During implementation of the JS instrumentation for this change the break was discovered, and now the semconv is being updated to address that break. If the PR had been merged blindly, we may never have discovered this issue. Even if it was discovered, it would have resulted in even more thrash (potentially breaking) when the spec was fixed after the change was merged.

[austinlparker]

@jack-berg does https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/telemetry-stability.md#stable-instrumentations resolve this?

[trask]

(in particular)

Stable instrumentations authored by OpenTelemetry SHOULD NOT produce telemetry that is not described by OpenTelemetry semantic conventions.

[jack-berg]

If I recall correctly, the context for this issue was about lambda instrumentation. There was disagreement over a PR that was merged to semantic conventions and the lambda maintainers declined PRs to reflect the changes. So the language about stable instrumentation is good, but not good enough to resolve this situation.

But its tricky because there are valid reasons why a maintainer might decline to accept PRs for a new experimental convention. For example, they might wish to avoid churn if more changes are anticipated.