Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Address #337 #344

Closed
wants to merge 3 commits into from
Closed

Address #337 #344

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ef0d049
Address #337
SergeyKanzhelev Oct 22, 2019
7306974
Use MUST language instead of needs to
SergeyKanzhelev Oct 22, 2019
9f6e35f
added rationale and expanded section about 64bit tracing systems
SergeyKanzhelev Oct 24, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions spec/20-http_header_format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,12 +102,19 @@ trace-flags = 2HEXDIGLC ; 8 bit flags. Currently, only one bit is used. S

This is the ID of the whole trace forest and is used to uniquely identify a [distributed trace](https://w3c.github.io/trace-context/#dfn-distributed-traces) through a system. It is represented as a 16-byte array, for example, `4bf92f3577b34da6a3ce929d0e0e4736`. All bytes as zero (`00000000000000000000000000000000`) is considered an invalid value.


A vendor SHOULD generate globally unique values for `trace-id`. Many unique identification generation algorithms create IDs where one part of the value is constant (often time- or host-based), and the other part is a randomly generated value. Because tracing systems may make sampling decisions based on the value of `trace-id`, for increased interoperability vendors MUST keep the random part of `trace-id` ID on the left side.


When a system operates with a `trace-id` that is shorter than 16 bytes, it SHOULD fill-in the extra bytes with random values rather than zeroes. Let's say the system works with an 8-byte `trace-id` like `3ce929d0e0e4736`. Instead of setting `trace-id` value to `0000000000000003ce929d0e0e4736` it SHOULD generate a value like `4bf92f3577b34da6a3ce929d0e0e4736` where `4bf92f3577b34da6a` is a random value or a function of time and host value.

When a system operates with a `trace-id` that is shorter than 16 bytes, on new
trace-id generation it SHOULD fill-in the extra bytes with random values rather
than zeroes. Let's say the system works with an 8-byte `trace-id` like
`23ce929d0e0e4736`. Instead of setting `trace-id` value to
`23ce929d0e0e47360000000000000000` (note, that random part is kept on the left
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As mentioned by others, this example is backwards and doesn't match the comment in parenthesis.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

random part is kept to the left. Why is it not matching?

Copy link

@nicmunroe nicmunroe Oct 28, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the big problem here is the words "random part" can be interpreted multiple ways. The text says that the "random part is kept on the left" but I think it means to say "the original 8-byte trace ID is kept on the left". Yes/no? This section is discussing backfilling with random values vs. zeros, so when you say "random part is kept on the left" I'm reading that as the random backfilling on the left. But you're using the original 8-byte trace ID on the left, not random-backfill values, and the right side is all zeros, which nobody here is arguing should be done.

And looking at it from the zeros point of view: why is the 0000000000000000 on the right here? The text says "Instead of setting trace-id value to
23ce929d0e0e47360000000000000000". Who would ever set it to 23ce929d0e0e47360000000000000000? If it was zero-backfilled wouldn't it be 000000000000000023ce929d0e0e4736? i.e. the backfilled zeros would be on the left.

side as mentioned one paragraph above) it SHOULD generate a value like
`4bf92f3577b34da623ce929d0e0e4736` where `4bf92f3577b34da6` is a random value or
a function of time and host value. Note, that on receiving a `trace-id` which is
longer than what system operates with, even though `trace-id` may be recorded
with the shorter id, the entire trace-id needs to be propagated to the
downstream components.

**Note**: Even though a system may operate with a shorter `trace-id` for [distributed trace](https://w3c.github.io/trace-context/#dfn-distributed-traces) reporting, the full `trace-id` MUST be propagated to conform to the specification.

Expand Down