belgif
W3C Trace Context and baggage headers
There are W3C standards for trace context and baggage HTTP headers, which are compatible with the OpenTelemetry specification.
We get the question from time to time why the REST guide doesn't recommend these instead of its own BelGov-(Related-)Trace-Id headers, or how they can work together with an OpenTelemetry tracing infrastructure.
Also see discussion in https://github.com/belgif/rest-guide-validator/issues/114 .
The rule [trc-header] does allow other headers for use internally in an organization: Within an organization, other headers MAY be used for tracing calls, for instance the headers supported by tracing tools like Zipkin or Jaeger. We can modify this rule to use the W3C headers instead of Zipkin/Jaeger ones.
The W3C trace standards didn't exist yet when the Belgif guideline was authored, but there are also other concerns to adopt it. The W3C/OTel tracing is primarily useful within an organization's trust boundaries, but when an API is called from a 3rd party external client, they are harder to apply:
- for security and privacy reasons, use of the W3C/OTel headers would need to be limited severely
- it is more difficult for external clients not using an OpenTelemetry-compatible stack, to generate the proper W3C Trace Context headers (trace-id, parent-id, flags, tracestate) than it is to create a
BelGov-Trace-Idvalue
API providers could support both BelGov and W3C dynamically depending on the client being located within the trust boundary or not.
I'll create a PR for review by the WG.
PR created.
A difficulty to map between OTel- and BelGov-headers is that OTel requires both trace-id (16 bytes) and span-id (8 bytes), while belgif only has a single BelGov-Trace-Id (max 16 bytes) that can't contain both.
Should we recommend to use the span-id? Its shorter so more chance on collisions, but it is unique per call.
a fifty-fifty chance of a collision after only five billion values. You’re at 10% chance before even two billion, and 1% after 609 million from https://news.ycombinator.com/item?id=25302611
On the other hand if you choose to include trace-id, probablity on collisions is negligable, but the value isn't unique when multiple calls are made within same trace tree, and there is some risk on information exposure:
Another privacy risk of the traceparent field is the ability to correlate requests made as part of a single transaction. A downstream service may track and correlate two or more requests made in a single transaction and may make assumptions about the identity of the caller of a request based on information from another request.
from https://w3c.github.io/trace-context/#privacy-of-traceparent-field