Agree on the scope for HTTP semantic conventions v1.0

[denisivan0v]

Several months ago the OTEP that captures the scope and roadmap for HTTP semantic conventions v1.0 (along with the scope for vNext) was reviewed and merged (open-telemetry/oteps#174). It was actively discussed at Instrumentation SIG meetings (Tue 4PM PST) and it was an agreement within the group, but it feels that there is no shared understanding with TC on the path of bringing HTTP semantic conventions to v1.0 (stable). Submitting this issue to fill this gap.

As a part of the OTEP, 4 main items were identified as required to be resolved before v1.0:

• Error status defaults (resolved with 4xx client errors to be left unset #2309)
• Required attribute sets (in progress Remove alternative attribute sets from HTTP semantic conventions #2469)
• Span structure for HTTP retries and redirects (resolved with Define span structure for HTTP retries and redirects #2078, span links part extracted to a separate PR - Add span links for HTTP retries and redirects #2393)
• Context propagation (moved to vNext)

The group also maintains the Project board that reflects the current status for this work.

That said, the only item left before HTTP semantic conventions v1.0 is #2469 (which also resolves #2114, #2056 and #2028).
It would be beneficial to discuss this scope once again at the upcoming Spec meeting to make sure the Instrumentation SIG and TC are on the same page.

@open-telemetry/technical-committee, @open-telemetry/specs-trace-approvers

[denisivan0v]

@tigrannajaryan as per your suggestion given at 4/19/2022 #234 Spec SIG meeting at 8am PT

Suggestion was to reach out to SDK maintainers via Slack, maintainer’s call and once ready individual SDK repo issues

I'm going to (on behalf of Instrumentation SIG) reach out to maintainers of the following SDKs:

• Java
• .NET
• Python

The goal is to get an explicit answer to the question: "are you comfortable with the HTTP semantic conventions specification being marked stable, within the scope captured in #2499"?

Once confirmations from maintainers of these 3 SDKs are received, I will reach out to maintainers of the rest of SDKs via maintainers meeting (Monday 9am PT) asking to express any disagreements.

Obtaining these confirmations and absence of disagreements means that everyone (including Instrumentation SIG, TC and SDK maintainers) is ready to approve a PR marking HTTP semantic conventions specification stable.

Is my understanding correct? If yes, can you please also suggest how best to record confirmations from the maintainers of those 3 SDKs?

[tigrannajaryan]

@denisivan0v

The goal is to get an explicit answer to the question: "are you comfortable with the HTTP semantic conventions specification being marked stable, within the scope captured in #2499"?

There are 2 possible ways forward:

1. If you are reasonably certain what your proposal is the right approach then you are primarily looking for confirmation from language SIG that they can implement it and agree with it. In this case it is best to wait until all PRs are merged, then ask language maintainers if they have any objections to move the "HTTP Spans" document from "Experimental" to "Stable". This will be one last PR that only changes the document status.
2. If, however you are looking for more active feedback and you are interested in opinions of language SIGs about how HTTP spans should be recorded, then you need to begin earlier (now), work directly with language maintainers, show them your proposal, ask for feedback, incorporate the feedback, etc. This is typically done via an OTEP, which describes the entire initiative in full details (not like the "roadmap" OTEP that you submitted earlier). It may be too late for this, but maybe not. This again depends on how certain you are that what you proposed in the form of PRs to spec repo is the right approach and how much objection you expect from language maintainers.

Option 1 may be more preferable this time, since you already made significant progress and going back to OTEP stage can slow down things. For the future I would highly advise to start and go though a proper OTEP process (again, not just a roadmap OTEP), which is designed exactly to facilitate complicated initiatives like this.

If yes, can you please also suggest how best to record confirmations from the maintainers of those 3 SDKs?

You can ask a maintainer from each language to review and approve the PR or to comment on the issue.

[jamesmoessis]

@trask pointed out in the Java SIG that resolution to #2056 (http.target vs path & query) is a minor thing that would be nice.

This is also something that most likely could be translated using schemas in later versions, if we can't reach a decision before v1.

[tedsuo]

@tigrannajaryan can we clarify that 3 SIGs would be enough of a maintainer review? Reaching out to every single language is more review overhead then we normally go with.

[tigrannajaryan]

@tigrannajaryan can we clarify that 3 SIGs would be enough of a maintainer review? Reaching out to every single language is more review overhead then we normally go with.

Yes, I think it is fine. I suggested it primarily because I thought maintainers may have suggestions, not because I thought they may want to veto it.

[lmolkova]

closing this, since HTTP conventions are stable