Skip to content

Commit

Permalink
Specify uniqueness of tracestate keys as the sender's responsibility
Browse files Browse the repository at this point in the history
This partially resolves w3c#446.

This adds a new rule to "Mutating the tracestate Field" that makes it
clear that a sender must not create duplicated tracestate keys. It is a
non-breaking change because the section "Combined Header Value" already
had called that out with "Only one entry per key is allowed". Basically
this adds that rule to the section it actually belongs into.

Having that as the responsibility of the sender seems to be consensus in

There seems to be no consensus yet whether an implementation should
clean up a tracestate value it receives by discarding duplicate keys
that it does not own. Thus, that aspect is not considered in this
change.
  • Loading branch information
basti1302 committed Dec 14, 2021
1 parent 3081b03 commit 81c8091
Showing 1 changed file with 4 additions and 2 deletions.
6 changes: 4 additions & 2 deletions spec/20-http_request_header_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,7 @@ The `tracestate` value is the concatenation of trace graph key/value pairs

Example: `vendorname1=opaqueValue1,vendorname2=opaqueValue2`

Only one entry per key is allowed because the entry represents that last position in the trace. Hence vendors must overwrite their entry upon reentry to their tracing system.
Only one entry per key is allowed. Hence vendors MUST update their entry instead of adding it twice when propagating a modfied `tracestate` header downstream.

For example, if a vendor name is Congo and a trace started in their system and then went through a system named Rojo and later returned to Congo, the `tracestate` value would not be:

Expand All @@ -306,6 +306,8 @@ For example, if a vendor name is Congo and a trace started in their system and t
Instead, the entry would be rewritten to only include the most recent position:
`congo=congosSecondPosition,rojo=rojosFirstPosition`

See [Mutating the tracestate Field](#mutating-the-tracestate-field) for details.

#### tracestate Limits:

Vendors SHOULD propagate at least 512 characters of a combined header. This length includes commas required to separate list items and optional white space (`OWS`) characters.
Expand Down Expand Up @@ -353,6 +355,6 @@ Vendors receiving a `tracestate` request header MUST send it to outgoing request

Following are allowed mutations:

- **Add a new key/value pair**. The new key/value pair SHOULD be added to the beginning of the list.
- **Add a new key/value pair**. The new key/value pair SHOULD be added to the beginning of the list. Adding a key/value pair MUST NOT result in the same key being present multiple times.
- **Update an existing value**. The value for any given key can be updated. Modified keys SHOULD be moved to the beginning (left) of the list.
- **Delete a key/value pair**. Any key/value pair MAY be deleted. Vendors SHOULD NOT delete keys that were not generated by them. The deletion of an unknown key/value pair will break correlation in other systems. This mutation enables two scenarios. The first is that proxies can block certain `tracestate` keys for privacy and security concerns. The second scenario is a truncation of long `tracestate`s.

0 comments on commit 81c8091

Please sign in to comment.