From 08f557b9f6750881ba9f9018ab45384e7d1494a6 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 9 Nov 2021 13:08:58 -0500 Subject: [PATCH 01/12] Add the random trace id flag --- spec/20-http_request_header_format.md | 24 ++++++++++++++++++++++-- spec/60-trace-id-format.md | 7 ++++++- 2 files changed, 28 insertions(+), 3 deletions(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index e7a400c0..101941ba 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -138,8 +138,6 @@ boolean sampled = (traceFlags & FLAG_SAMPLED) == FLAG_SAMPLED; ##### Sampled flag -The current version of this specification (`00`) only supports a single flag called `sampled`. - When set, the least significant bit (right-most), denotes that the caller may have recorded trace data. When unset, the caller did not record trace data out-of-band. There are a number of recording scenarios that may break distributed tracing: @@ -176,6 +174,28 @@ There are two additional options that vendors MAY follow: - A component that makes a deferred or delayed recording decision may communicate the priority of a recording by setting `sampled` flag to `1` for a subset of requests. - A component may also fall back to probability sampling and set the `sampled` flag to `1` for the subset of requests. +##### Random Trace ID Flag + + + +When set, the second least significant bit (second from the right), denotes that the least significant (right-most) 7 bytes of the trace ID MUST be random (or pseudo-random). +When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). + ##### Other Flags The behavior of other flags, such as (`00000100`) is not defined and is reserved for future use. Vendors MUST set those to zero. diff --git a/spec/60-trace-id-format.md b/spec/60-trace-id-format.md index 204b7353..21a9b382 100644 --- a/spec/60-trace-id-format.md +++ b/spec/60-trace-id-format.md @@ -22,6 +22,9 @@ concerns](#privacy-considerations) of exposing unwanted information. Randomness also allows tracing vendors to base sampling decisions on `trace-id` field value and avoid propagating an additional sampling context. +If the `random-trace-id` flag is set, the least significant 7 bytes of the +`trace-id` MUST be randomly (or pseudo-randomly) generated. + As shown in the next section, it is important for `trace-id` to carry "uniqueness" and "randomness" in the right part of the `trace-id`, for better inter-operability with some existing systems. @@ -50,7 +53,9 @@ systems with these existing systems, the following practices are recommended: compliant 16 bytes `trace-id` from a shorter identifier, it SHOULD left pad the original identifier with zeroes. For example, the identifier `53ce929d0e0e4736`, SHOULD be converted to `trace-id` value - `000000000000000053ce929d0e0e4736`. + `000000000000000053ce929d0e0e4736`. If the resultant `trace-id` value does + not satisfy the constraints of the `random-trace-id` flag, the flag MUST + be set to `0`. 2. When a system receives an inbound message and needs to convert the 16 bytes `trace-id` to a shorter identifier, the rightmost part of `trace-id` SHOULD be used as this identifier. For instance, if the value of `trace-id` was From b32f18a8d8784161d0ac56ce9d3e18726255b251 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 9 Nov 2021 14:59:32 -0500 Subject: [PATCH 02/12] Wording --- spec/20-http_request_header_format.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index 101941ba..ebf850f6 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -180,11 +180,11 @@ There are two additional options that vendors MAY follow: TODO: how many random bytes are needed? 7 was chosen as it can be efficiently represented as a 64-bit signed or unsigned integer. -8 would require an unsigned long which is not supported by some languages (like Java). +8 would require an unsigned long which is not supported by some languages (like Java and Go). 63 bits would be possible, but would require a more complex description that may be more difficult to understand. TODO: Which specific bytes should be random? -The least significant bytes were chosen because some tracing systems are known to use the most significant +The right-most bytes were chosen because some tracing systems are known to use the left-most portion of the trace id for non-random data such as a timestamp component. TODO: Do we want to place any restrictions on the randomness or is saying "MUST be random" enough? @@ -193,7 +193,7 @@ https://datatracker.ietf.org/doc/html/rfc4122#section-4.4 --> -When set, the second least significant bit (second from the right), denotes that the least significant (right-most) 7 bytes of the trace ID MUST be random (or pseudo-random). +When set, the second least significant bit (second from the right), denotes that the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). ##### Other Flags From f65d9a5932eae5b2973941896df67a0d54f290ca Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 9 Nov 2021 16:08:33 -0500 Subject: [PATCH 03/12] Wording Co-authored-by: Yuri Shkuro --- spec/60-trace-id-format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/60-trace-id-format.md b/spec/60-trace-id-format.md index 21a9b382..b9bf8825 100644 --- a/spec/60-trace-id-format.md +++ b/spec/60-trace-id-format.md @@ -22,7 +22,7 @@ concerns](#privacy-considerations) of exposing unwanted information. Randomness also allows tracing vendors to base sampling decisions on `trace-id` field value and avoid propagating an additional sampling context. -If the `random-trace-id` flag is set, the least significant 7 bytes of the +If the `random-trace-id` flag is set, the right-most 7 bytes of the `trace-id` MUST be randomly (or pseudo-randomly) generated. As shown in the next section, it is important for `trace-id` to carry From 8617fefe7ca096a08ba0474bc79b4f37785e190e Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 11 Apr 2022 17:06:15 -0400 Subject: [PATCH 04/12] Add SHOULD wording to trace id randomness --- spec/20-http_request_header_format.md | 31 ++++++++------------------- 1 file changed, 9 insertions(+), 22 deletions(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index c1fdca60..d9f33777 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -100,13 +100,17 @@ trace-flags = 2HEXDIGLC ; 8 bit flags. Currently, only one bit is used. S #### trace-id -This is the ID of the whole trace forest and is used to uniquely identify a distributed trace through a system. It is represented as a 16-byte array, for example, `4bf92f3577b34da6a3ce929d0e0e4736`. All bytes as zero (`00000000000000000000000000000000`) is considered an invalid value. +This is the ID of the whole trace forest and is used to uniquely identify a distributed trace through a system. +It is represented as a 16-byte array, for example, `4bf92f3577b34da6a3ce929d0e0e4736`. +All bytes as zero (`00000000000000000000000000000000`) is considered an invalid value. -If the `trace-id` value is invalid (for example if it contains non-allowed characters or all zeros), vendors MUST ignore the `traceparent`. +The value of `trace-id` SHOULD be globally unique. +It is RECOMMENDED that implementers randomly (or pseudo-randomly) generate the `trace-id` field, and set the corresponding [random trace id flag](#random-trace-id-flag). +This ensures, to a reasonable degree, global uniqueness, and addresses some privacy and security considerations. +Even in cases where it is not possible to randomly (or pseudo-randomly) generate the `trace-id`, it is RECOMMENDED that at least the right-most 7 bytes of the `trace-id` be randomly generated. +For more details, see [considerations for trace-id field generation](#considerations-for-trace-id-field-generation). -See [considerations for trace-id field -generation](#considerations-for-trace-id-field-generation) for recommendations -on how to operate with `trace-id`. +If the `trace-id` value is invalid (for example if it contains non-allowed characters or all zeros), vendors MUST ignore the `traceparent`. #### parent-id @@ -176,23 +180,6 @@ There are two additional options that vendors MAY follow: ##### Random Trace ID Flag - - When set, the second least significant bit (second from the right), denotes that the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). From 6206ae8958f3ba4b08fb3580388b3a98c04a2a6d Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 11 Apr 2022 17:06:50 -0400 Subject: [PATCH 05/12] Specify that implementers SHOULD set random flag when appropriate --- spec/20-http_request_header_format.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index d9f33777..240de765 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -183,6 +183,10 @@ There are two additional options that vendors MAY follow: When set, the second least significant bit (second from the right), denotes that the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). +When at least the right-most 7 bytes of the `trace-id` are randomly (or pseudo-randomly) generated, the random trace ID flag SHOULD be set to `1`. +This allows downstream consumers know that the right-most 7 bytes of the trace ID are sufficiently random, and enables them to implement features such as trace sampling or database sharding based on these bytes. +For additional information, see [considerations for trace-id field generation](#considerations-for-trace-id-field-generation). + ##### Other Flags The behavior of other flags, such as (`00000100`) is not defined and is reserved for future use. Vendors MUST set those to zero. From 3eb81c243f3c53d0212b85fb0134202619ee600b Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Apr 2022 11:41:05 -0400 Subject: [PATCH 06/12] Random flag means at least 7 bytes --- spec/20-http_request_header_format.md | 2 +- spec/60-trace-id-format.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index 240de765..69532d39 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -180,7 +180,7 @@ There are two additional options that vendors MAY follow: ##### Random Trace ID Flag -When set, the second least significant bit (second from the right), denotes that the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). +When set, the second least significant bit (second from the right), denotes that the at least the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). When at least the right-most 7 bytes of the `trace-id` are randomly (or pseudo-randomly) generated, the random trace ID flag SHOULD be set to `1`. diff --git a/spec/60-trace-id-format.md b/spec/60-trace-id-format.md index 48c8fc5c..ae1d073c 100644 --- a/spec/60-trace-id-format.md +++ b/spec/60-trace-id-format.md @@ -22,7 +22,7 @@ concerns](#privacy-considerations) of exposing unwanted information. Randomness also allows tracing vendors to base sampling decisions on `trace-id` field value and avoid propagating an additional sampling context. -If the `random-trace-id` flag is set, the right-most 7 bytes of the +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. As shown in the next section, if part of the `trace-id` is nonrandom, From 05f145ff5428cb9c292f776362ca6db8be0825cf Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Apr 2022 11:42:44 -0400 Subject: [PATCH 07/12] Flag wording --- spec/20-http_request_header_format.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index 69532d39..fa2901b9 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -180,7 +180,9 @@ There are two additional options that vendors MAY follow: ##### Random Trace ID Flag -When set, the second least significant bit (second from the right), denotes that the at least the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). +The second least significant bit of the trace-flags field denotes the random-trace-id flag. +If that flag is set, the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). +If the flag is not set, the trace ID MAY still be randomly (or pseudo-randomly) generated. When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). When at least the right-most 7 bytes of the `trace-id` are randomly (or pseudo-randomly) generated, the random trace ID flag SHOULD be set to `1`. From 971d081c5137126fa798aba55b5c6d153f992a34 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Apr 2022 11:45:31 -0400 Subject: [PATCH 08/12] Only 2 flags are specified --- spec/20-http_request_header_format.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index fa2901b9..ceac02b4 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -120,6 +120,8 @@ Vendors MUST ignore the `traceparent` when the `parent-id` is invalid (for examp #### trace-flags +The current version of this specification (`00`) supports only two flags: `sampled` and `random-trace-id`. + An 8-bit field that controls tracing flags such as sampling, trace level, etc. These flags are recommendations given by the caller rather than strict rules to follow for three reasons: 1. An untrusted caller may be able to abuse a tracing system by setting these flags maliciously. From 032f220a1ec31418c7992b989fd8da1cfb502aa3 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Apr 2022 14:08:20 -0400 Subject: [PATCH 09/12] Remove redundant wording --- spec/20-http_request_header_format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index ceac02b4..569c7d1c 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -188,7 +188,7 @@ If the flag is not set, the trace ID MAY still be randomly (or pseudo-randomly) When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). When at least the right-most 7 bytes of the `trace-id` are randomly (or pseudo-randomly) generated, the random trace ID flag SHOULD be set to `1`. -This allows downstream consumers know that the right-most 7 bytes of the trace ID are sufficiently random, and enables them to implement features such as trace sampling or database sharding based on these bytes. +This allows downstream consumers to implement features such as trace sampling or database sharding based on these bytes. For additional information, see [considerations for trace-id field generation](#considerations-for-trace-id-field-generation). ##### Other Flags From 41744ee82b74e7117b18d8fd5bb0005446ed8b78 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 12 Apr 2022 14:09:16 -0400 Subject: [PATCH 10/12] At least 7 bytes --- spec/20-http_request_header_format.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index 569c7d1c..ecf06147 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -183,7 +183,7 @@ There are two additional options that vendors MAY follow: ##### Random Trace ID Flag The second least significant bit of the trace-flags field denotes the random-trace-id flag. -If that flag is set, the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). +If that flag is set, at least the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). If the flag is not set, the trace ID MAY still be randomly (or pseudo-randomly) generated. When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). From 7985b6a1ea8520f01473502e8be33b5070889a86 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 13 Apr 2022 08:28:01 -0400 Subject: [PATCH 11/12] Review comments --- spec/20-http_request_header_format.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index ecf06147..7a615b46 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -132,14 +132,18 @@ You can find more in the section [Security considerations](#security-considerati Like other fields, `trace-flags` is hex-encoded. For example, all `8` flags set would be `ff` and no flags set would be `00`. -As this is a bit field, you cannot interpret flags by decoding the hex value and looking at the resulting number. For example, a flag `00000001` could be encoded as `01` in hex, or `09` in hex if present with the flag `00001000`. A common mistake in bit fields is forgetting to mask when interpreting flags. +As this is a bit field, the flags cannot be interpreted by a simple equality comparison. +For example, both `01` (`00000001`) and `03` (`00000011`) represent that the trace has been sampled because the sampled flag (`00000001`) is set, and `03` and `02` (`00000010`) both represent that at least the right-most 7 bytes of the `trace-id` are randomly (or pseudo-randomly) generated because the random bit (`00000010`) is set. +A common mistake when interpreting bit-fields is using a comparison of the whole number rather than interpreting a single bit. Here is an example of properly handling trace flags: ``` java static final byte FLAG_SAMPLED = 1; // 00000001 +static final byte FLAG_RANDOM = 2; // 00000010 ... boolean sampled = (traceFlags & FLAG_SAMPLED) == FLAG_SAMPLED; +boolean random = (traceFlags & FLAG_RANDOM) == FLAG_RANDOM; ``` ##### Sampled flag @@ -185,7 +189,7 @@ There are two additional options that vendors MAY follow: The second least significant bit of the trace-flags field denotes the random-trace-id flag. If that flag is set, at least the right-most 7 bytes of the trace ID MUST be random (or pseudo-random). If the flag is not set, the trace ID MAY still be randomly (or pseudo-randomly) generated. -When unset, the trace ID may be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). +When unset, the trace ID MAY be generated in any way that satisfies the requirements of the [trace ID format](#trace-id). When at least the right-most 7 bytes of the `trace-id` are randomly (or pseudo-randomly) generated, the random trace ID flag SHOULD be set to `1`. This allows downstream consumers to implement features such as trace sampling or database sharding based on these bytes. From 2276524ad5e1bc9a9abb068d12db5f640dd4282b Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 13 Apr 2022 09:38:14 -0400 Subject: [PATCH 12/12] Remove RECOMMENDED wording --- spec/20-http_request_header_format.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/spec/20-http_request_header_format.md b/spec/20-http_request_header_format.md index 7a615b46..50b3d19e 100644 --- a/spec/20-http_request_header_format.md +++ b/spec/20-http_request_header_format.md @@ -105,9 +105,9 @@ It is represented as a 16-byte array, for example, `4bf92f3577b34da6a3ce929d0e0e All bytes as zero (`00000000000000000000000000000000`) is considered an invalid value. The value of `trace-id` SHOULD be globally unique. -It is RECOMMENDED that implementers randomly (or pseudo-randomly) generate the `trace-id` field, and set the corresponding [random trace id flag](#random-trace-id-flag). -This ensures, to a reasonable degree, global uniqueness, and addresses some privacy and security considerations. -Even in cases where it is not possible to randomly (or pseudo-randomly) generate the `trace-id`, it is RECOMMENDED that at least the right-most 7 bytes of the `trace-id` be randomly generated. +One recommended method to ensure global uniqueness, as well as to address some privacy and security considerations, to a satisfactory degree of certainty is to randomly (or pseudo-randomly) generate the `trace-id`. +Implementers SHOULD use a `trace-id` generation method which randomly (or pseudo-randomly) generates at least the right-most 7 bytes of the ID. +If the right-most 7 bytes are randomly (or pseudo-randomly) generated, the corresponding [random trace id flag](#random-trace-id-flag) SHOULD be set. For more details, see [considerations for trace-id field generation](#considerations-for-trace-id-field-generation). If the `trace-id` value is invalid (for example if it contains non-allowed characters or all zeros), vendors MUST ignore the `traceparent`.