CR Request for W3C TraceContext Level 2 Specification

[kalyanaj]

Document title, URLs, estimated publication date

Title: Trace Context Level 2
URL: https://w3c.github.io/trace-context/ (latest editors' draft)
Estimated publication date: After approval (no other strong deadline).

Abstract

This specification defines standard HTTP headers and a value format to propagate context information that enables distributed tracing scenarios. The specification standardizes how context information is sent and modified between services. Context information uniquely identifies individual requests in a distributed system and also defines a means to add and propagate provider-specific context information.

Status

Level 1 of this specification is already in Recommendation status since 2019. This is a minor incremental update to it called Trace Context Level 2:
https://w3c.github.io/trace-context/ (latest editor's draft)
https://www.w3.org/TR/trace-context-2/ (FPWD)

Link to group's decision to request transition

We discussed this in the Distributed Tracing WG meeting on 03/28/2023. The group unanimously decided to request this transition. Meeting notes are at: https://docs.google.com/document/d/1EaY1zhmlOut4qZzpFue4vLc96_GrRWMtmzXYLfd1Ehc/edit#.

Changes

The main changes are:

• It introduces a new "flag" in the traceparent header called the random-trace-id flag. This is to indicate if the trace-id was generated randomly (or pseudo-randomly).
• If the random-trace-id flag is set, at least the right-most 7 bytes of the trace-id MUST be randomly (or pseudo-randomly) generated.

Requirements satisfied

No specific requirements document was created.

Dependencies met (or not)

Please see next section.

Wide Review

Yes the wide review was done (w3c/trace-context#492) and issues have been addressed.

Issues addressed

• Change the defining document for HTTP from RFC7230 to RFC9110 (Change the defining document for HTTP from RFC7230 to RFC9110 trace-context#519)
• When headers should be propagated in browsers should be made more clear (When headers should be propagated in browsers should be made more clear trace-context#510)
• Adopt either span-id or parent-id for section headings (Adopt either span-id or parent-id for section headings trace-context#509)
• Why should keys be restricted to lowercase ASCII? (Why should keys be restricted to lowercase ASCII? trace-context#508)
• Version number relationship to ASCII and UTF-8 (Version number relationship to ASCII and UTF-8 trace-context#507)
• Specification of lowercase is incomplete (specification of lowercase is incomplete trace-context#506)

Formal Objections

None so far

Implementation

open-telemetry/oteps#226 is an OpenTelemetry sampler specification enhancement proposal that references the above specification.
Minimum CR duration: 3 months
Exit criteria: At least 2 implementations adopting this specification and making use of it. The test suite will be updated as well.

Patent disclosures

None

[ylafon]

Hi @kalyanaj
Looking at the diff from the FPWD and the editor's draft linked, I see the whole section 4 Trace Context HTTP Response Headers Format as not been reviewed.
Could you clarify?
Thanks

[plehegar]

we have a dedicated branch for level-2. I'll generate a WD for it to make it clear which document should be published as CR.

[ylafon]

I would note also that I found a TAG review of the Trace Context Level 2 changes, so the diff from v1 REC to v2 FPWD, but not the review of Trace Context Level 1. Did that happen, or what is missed?

[plehegar]

I created a snapshot of the level 2 branch:

• Level 2 2023-04-05
• Diff with FPWD

[plehegar]

I could not locate a formal TAG review request in late 2018.

I did find minutes from TPAC 2018, which include discussion on structured headers.

[plehegar]

See also w3c/trace-context#197 (comment)

[ylafon]

I could not locate a formal TAG review request in late 2018.

I did find minutes from TPAC 2018, which include discussion on structured headers.

That document is private

[plehegar]

Also published a WD: https://www.w3.org/TR/2023/WD-trace-context-2-20230406/

[plehegar]

I could not locate a formal TAG review request in late 2018.
I did find minutes from TPAC 2018, which include discussion on structured headers.

That document is private

:(

Fixed.

[plehegar]

SOTD for CR:
[[
This new version adds considerations for the generation of the trace-id and span-id fields, and adds the random trace ID flag.

This document was published by the Distributed Tracing Working Group as a Candidate Recommendation Snapshot using the Recommendation track.
Publication as a Candidate Recommendation does not imply endorsement by W3C and its Members. A Candidate Recommendation Snapshot has received wide review, is intended to gather implementation experience, and has commitments from Working Group members to royalty-free licensing for implementations.
This Candidate Recommendation is not expected to advance to Proposed Recommendation any earlier than 07 July 2023.

The Working Group instends to demonstrate at least 2 implementations adopting this specification and making use of it, using a test suite.

This document was produced by a group operating under the 1 August 2017 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 2 November 2021 W3C Process Document.
]]

[ylafon]

Thanks for the clarifications and new document published.
Transition is approved.

[plehegar]

pubreq: https://lists.w3.org/Archives/Team/webreq/2023Apr/0014.html

[plehegar]

https://www.w3.org/TR/2023/CR-trace-context-2-20230418/