Clarify that attribute requirement levels apply to instrumentation libraries

[trask]

Based on discussion in semconv stability WG

Closes #3283

Changes

Clarifies that attribute requirement levels apply to instrumentation. And that, because users can transform their telemetry in a number of ways (e.g. metric views, span processors, and collector transformations), these requirement levels cannot be relied on by telemetry consumers.

[reyang]

💯

[Oberon00]

these requirement levels cannot be relied on by telemetry consumers

Really? Then their only purpose is to make the life of instrumentation authors more difficult?

I think some caveat like "Backends MAY offer reduced or no functionality when users configure their pipeline to omit required attributes." or something in that direction should be added. Right now, this is saying "uses can do whatever they like with their attributes and backends must be prepared for everything"

Basically I want this spec to be worded such that I can tell users, "see, it is OK when you do this, but then please don't complain if things break". Right now it is worded in such a way that the user could come complaining to the backend and say "you are relying on http.url, but here it clearly says you must not rely on anything"

[tigrannajaryan]

these requirement levels cannot be relied on by telemetry consumers

Really? Then their only purpose is to make the life of instrumentation authors more difficult?

I think some caveat like "Backends MAY offer reduced or no functionality when users configure their pipeline to omit required attributes." or something in that direction should be added. Right now, this is saying "uses can do whatever they like with their attributes and backends must be prepared for everything"

Basically I want this spec to be worded such that I can tell users, "see, it is OK when you do this, but then please don't complain if things break". Right now it is worded in such a way that the user could come complaining to the backend and say "you are relying on http.url, but here it clearly says you must not rely on anything"

+1. I don't understand the purpose of the semconv requirements if I can't rely on them as a consumer at all.

Sure, I understand that once the produced telemetry leaves instrumentation it may be processed and transformed such that it no longer satisfies semconv requirements. However I would expect that this can happen only deliberately. I would not expect a well-written Otel-compliant processor (in SDK or in Collector) to silently garble the data such that it no longer matches the requirements of semconv.

[trask]

@Oberon00 @tigrannajaryan would it help clarify if I create an issue about adding semconv guarantees for consumers in the future? This PR is less not about "we don't want to do it" and more about "we aren't ready to do it".

[Oberon00]

IMHO, we were doing it, and now we'd stop doing it.

[Oberon00]

I added an alternative suggestion.

[tigrannajaryan]

IMHO, we were doing it, and now we'd stop doing it.

I agree. I think we have stronger guarantees now (before this PR). This PR weakens the guarantees and I am not sure I understand why we do that.

IMO the semantic conventions are first and foremost a contract between telemetry producers and consumers. If we are saying "this rule is for producers only", what's the purpose of that rule? If consumers can't rely on that rule why does the rule exist in the first place?

I get it, we don't want to promise more than we have to. But isn't the promise to consumers what makes the semantic conventions valuable?

I know we don't really enforce semantic conventions by technical means. It is a best effort from all parties (instrumentation, the processors, etc). But by adding weakening statements like this I think we signalling that even that "best effort" is not important (e.g. the processors may do whatever they want and can ignore the fact that semantic conventions are useful for consumers).

Again, there is probably something I am not seeing.

Based on discussion in semconv stability WG

@trask Perhaps you can tell a bit more about why the decision was made and that will help me understand the purpose of this change.

[trask]

based on feedback from @Oberon00 @tigrannajaryan and @pyohannes I have removed this part:

Because telemetry may be transformed in a number of ways with custom telemetry pipelines (e.g. metric views, span processors, and collector transformations), these requirement levels cannot be relied on by telemetry consumers.

this part remains:

Attribute requirement levels apply to the instrumentation library.

which I think is good enough, as it explicitly narrows the scope, and we can revisit what exactly attribute requirement levels mean for telemetry consumers in the future

[Oberon00]

OK, then since we start being specific should we elaborate what it means that they apply? Can I add attributes that are not in the semantic conventions? Do they apply to all users or only to code in official OTel repositories?

[Oberon00]

Hmm thinking about it again:

which I think is good enough, as it explicitly narrows the scope

doesn't this somehow contradict

and we can revisit what exactly attribute requirement levels mean for telemetry consumers in the future

As mentioned in the original PR version, there are telemetry producers (often at the same time consumer + producer) other than instrumentations. If we explicitly exclude them from semantic conventions, requiring them to adhere later will not be possible with our stability guarantees, will it?

Also at no point in our pipeline (except in the SDK implementation of the span API itself) can we be sure that the telemetry is actually produced by an instrumentation. E.g. a OnStart span processor (now excluded from semconv) could change an attribute value/type to something violating semantic conventions.

[trask]

Can I add attributes that are not in the semantic conventions?

I'm not aware of anything that says you cannot, so my understanding is yes

Do they apply to all users or only to code in official OTel repositories?

they apply to any instrumentation library that wants to follow the semantic conventions. I would expect that all official OTel repos will follow them where possible

If we explicitly exclude them from semantic conventions, requiring them to adhere later will not be possible with our stability guarantees, will it?

since we aren't defining any stability guarantees for consumers, how can we break that stability guarantee?

[pyohannes]

I agree with the strategy of leaving the impact of attribute requirement levels on consumers unspecified and of not making any assumptions in the spec of how consumer use them (or not use them).