Clarify specification compliance

[reyang]

Follow up open-telemetry/opentelemetry-go#3399 (comment) and open-telemetry/opentelemetry-go#3399 (comment).

Notes: Given the broad impact, we will leave this PR open for Dec. 2022 and Jan. 2023 to collect more perspectives.

[carlosalberto]

Also, let's mention this in the next Maintainers & Spec calls, so everybody is very aware of this ;)

[ahayworth]

This feels too broad to me - I would even go so far to say it's an overreaction.

I would feel much more comfortable if the specification instead carved out an exception for "experimental" work, so that we can encourage language SIGs to try new things to bring back to the broader community. Such experimental work should be clearly delineated as not part of the official SDK and subject to change / breakage at any point. We can put very stern warnings on such "experimental" extensions.

The language here is very broad, and I'm worried that it'll have a significant chilling effect on experimentation by language groups. Oftentimes it's useful to have a working implementation of things proposed to spec groups, and we should not discount the useful benefits of having it easily installable alongside official SDKs. With sufficient warnings and segmentation, this can be safe and effective.

The proposal here will create more problems than it solves, because any SDK that attempts to still do experimental work now faces a very fuzzy test for compliance. I don't foresee this providing a lot of clarity to the group as a whole. I believe we should not adopt this, and instead the Go SDK should simply not do what they were proposing to do. Does it really need to go farther?

[dyladan]

I agree with ahayworth. By the current wording it is actually disallowed to do prototypes of unspecified features, experimental semantic conventions, etc. In the meeting before the holiday we discussed that the API may be very strict but the SDK should be allowed to do some experimentation.

This also disallows the types of "convenience API wrappers" which I know @tedsuo has been pushing for for a long time, but others also find quite valuable.

[dyladan]

Requesting changes to indicate that I am not happy with the existing wording. I am not a spec approver so this is non-binding, but I am a maintainer. For details see my above comment.

[tedsuo]

I recommend that this section only apply to the instrumentation API.

[ahayworth]

instrumentation API

By this you mean "the API" vs "the SDK", yes? "Instrumentation API" is a new term to me, and I want to make sure I understand what you mean by it. 😄

[dyladan]

I think he's referring to "instrumentation API" to mean the API yes. All of the calls that instrumentations make into the API to actually create spans/metrics/logs. I think this does not include the helpers some languages have created for creating instrumentation infrastructure like patching code.

[MikeGoldsmith]

I also think that the wording is too limiting on experimentation and developing of features outside of the spec. There are many, many things that could potentially be added to the spec in the distant future so saying they cannot be added until the spec acknowledges them could be years apart.

As others have said, there should be strict guidelines on how the API looks and what it does, but SDK features for convenience should be allowed. Otherwise we're going to have bare SDKs and promote everything else be some sort of extension which I think will lead to community confusion and frustration.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[github-actions]

Closed as inactive. Feel free to reopen if this PR is still being worked on.

[github-actions]

Closed as inactive. Feel free to reopen if this PR is still being worked on.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[github-actions]

Closed as inactive. Feel free to reopen if this PR is still being worked on.

[dyladan]

I think this is an improvement but still doesn't allow for convenience APIs. Is that intentional? One example that is already available in several languages is with_span.

My thinking is that the convenience APIs might be scenario based and probably fit for separate components that users can optionally choose to use. If a particular programming language has some established pattern across majority of the scenarios, then it is already a "language specific" feature to me. I can give one example which is the "Dependency Injection" in .NET - there are folks who like the DI pattern and there are folks who do not, for ASP.NET Core applications it seems DI is the recommended path.
Regarding with_span, I actually consider this as "language specific", I treat "language specific" as the opposite of "language agnostic". with_span is useful for a subset of programming languages which leverage static scope or some syntactic sugar to make the code leaner.

IMO that is a dangerously broad definition of language specific and renders the rest of the text essentially meaningless.

@reyang do you not agree?

[reyang]

@reyang do you not agree?

I disagree with the "dangerously broad definition" part, I personally feel it is okay as an intentional ambiguity.
I agree that people could have different interpretations of what "language specific" means, I don't think we're in position to formally define what is "language specific".

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[dyladan]

If we're going to allow APIs to add helper methods specific to their langauge we should state that specifically. Also, what happens if the otel API adds a method with the same name in the future?

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[github-actions]

Closed as inactive. Feel free to reopen if this PR is still being worked on.