diff --git a/spec/20-http_header_format.md b/spec/20-http_header_format.md index 91f4aa2..a7f6b92 100644 --- a/spec/20-http_header_format.md +++ b/spec/20-http_header_format.md @@ -100,14 +100,18 @@ 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 that is used to uniquely identify a distributed trace through a system. It is represented as a 16-byte array, for example, `4bf92f3577b34da6a3ce929d0e0e4736`. -If the `trace-id` value is invalid (for example if it contains non-allowed characters or all zeros), vendors MUST ignore the `traceparent`. +For the interoperability between vendors, the 6 right most bytes of `trace-id` SHOULD be generated using random or pseudo-random number generation algorithm. If [[!RFC4122]] is used, only the Algorithms for Creating a UUID from Truly Random or Pseudo-Random Numbers can be used for `trace-id` value generation to satisfy the randomness requirement. See [considerations for trace-id field generation](#considerations-for-trace-id-field-generation) for recommendations on how to operate with `trace-id`. +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`. + #### parent-id This is the ID of this request as known by the caller (in some tracing systems, this is known as the `span-id`, where a `span` is the execution of a client request). It is represented as an 8-byte array, for example, `00f067aa0ba902b7`. All bytes as zero (`0000000000000000`) is considered an invalid value. diff --git a/spec/60-trace-id-format.md b/spec/60-trace-id-format.md index 204b735..aa1decb 100644 --- a/spec/60-trace-id-format.md +++ b/spec/60-trace-id-format.md @@ -6,7 +6,7 @@ practices will ensure better interoperability of different systems. ### Uniqueness of `trace-id` -The value of `trace-id` SHOULD be globally unique. This field is typically used +The value of `trace-id` SHOULD be globally unique. This field is used for unique identification of a distributed trace. It is common for distributed traces to span various components, including, for example, cloud services. Cloud services tend to serve variety of clients and have a very @@ -15,16 +15,19 @@ even when local uniqueness might seem like a good solution. ### Randomness of `trace-id` -Randomly generated value of `trace-id` SHOULD be preferred over other -algorithms of generating a globally unique identifiers. Randomness of `trace-id` -addresses some [security](#security-considerations) and [privacy -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. +For the interoperability between vendors, `trace-id` value SHOULD contain +random bytes. With other considerations, random bytes SHOULD be the right most +characters and at least 6 right most bytes (12 characters) SHOULD be generated +using random or pseudo-random number generation algorithm. -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. +Randomness of `trace-id` addresses some [security](#security-considerations) +and [privacy concerns](#privacy-considerations) of exposing unwanted +information. Randomness also allows tracing vendors to base various sharding +and sampling decisions on `trace-id` field value and avoid propagating an +additional sampling context. + +When [[!RFC4122]] is used for `trace-id` value generation, the required 12 +right most characters are generated as random or pseudo-random. Whenever possible fully randomly generated value of `trace-id` SHOULD be preferred. ### Handling `trace-id` for compliant platforms with shorter internal identifiers