Add documentation about binary encoding format that we are using and the trace context. #550
Conversation
|
cc @adriancole |
bogdandrutu
force-pushed
the
binaryencoding
branch
from
ea655ae
to
732e429
Compare
bogdandrutu
force-pushed
the
binaryencoding
branch
from
732e429
to
5919852
Compare
| @@ -0,0 +1,99 @@ | |||
| # BINARY FORMAT | |||
There was a problem hiding this comment.
maybe put a see-also link somewhere to the trace context repo?
Codecov Report
@@ Coverage Diff @@
## master #550 +/- ##
=======================================
Coverage 90% 90%
Complexity 566 566
=======================================
Files 110 110
Lines 2361 2361
Branches 211 211
=======================================
Hits 2125 2125
Misses 180 180
Partials 56 56Continue to review full report at Codecov.
|
…the trace context.
bogdandrutu
force-pushed
the
binaryencoding
branch
from
5919852
to
abd3387
Compare
|
Moved here census-instrumentation/opencensus-specs#1 |
| 102, 103, 104, 2, 1} | ||
|
|
||
| This corresponds to: | ||
| * `traceId` = {64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79} |
There was a problem hiding this comment.
This is very confusing because it uses byte values which happen to be valid ASCII characters, leading one to think that they are perhaps hex digits or something. It would be equally valid, and more instructive, to have a value like:
traceId = { 00, 127, 128, 255, 10, 13, 00, 00, 01, 02, 03, 04, 64, 65, 66, 67 }
There was a problem hiding this comment.
Good suggestion, can you make a quick PR to change this?
|
|
||
| Is the ID of the whole trace forest. It is represented as a 16-bytes array, | ||
| e.g. (in hex), `4bf92f3577b34da6a3ce929d0e0e4736`. All bytes 0 is considered invalid. | ||
|
|
There was a problem hiding this comment.
Can you please explicitly mention that these bytes are (I assume) in big-endian order (== network order), as opposed to little endian?
There was a problem hiding this comment.
no endianess implied here because trace-id is defined as a 16-byte array and span-id as a 8 byte array.
There was a problem hiding this comment.
To clarify, you're saying that this sequence of 32 hex digits 4bf92f3577b34da6a3ce929d0e0e4736, is to be understood as a sequence of 16 bytes with values 0x4b, 0xf9, 0x2f, 0x35, 0x77, 0xb3, 0x4d, 0xa6, 0xa3, 0xce, 0x92, 0x9d, 0x0e, 0x0e, 0x47, 0x36, in that order, but not to be interpreted as the 128 bit number 0x4bf92f3577b34da6a3ce929d0e0e4736 aka 100985939111033328018442752961257817910 in base 10.
This is confusing to me, because we do actually internally treat the span id as a 64 bit integer. I.e. we treat spanId = {97, 98, 99, 100, 101, 102, 103, 104} from your example as equivalent to (converting to hex digits) spanId = { 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67, 0x68 }, and then (concatenating the bytes, treating as big-endian and converting to decimal) spanId = 7017280452245743464 as from an HTTP header with value <traceid>/7017280452245743464;<options>
TODO: Add tags encoding.