From 0f868b7801ef9bcf6f7781d04d3396513bee7eee Mon Sep 17 00:00:00 2001 From: Ariel Valentin Date: Fri, 7 Jul 2023 16:07:29 -0500 Subject: [PATCH] docs: Add some clarity to ottrace docs (#522) --- propagator/ottrace/README.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/propagator/ottrace/README.md b/propagator/ottrace/README.md index 761a579e2..e6a5dde1e 100644 --- a/propagator/ottrace/README.md +++ b/propagator/ottrace/README.md @@ -7,8 +7,8 @@ The `opentelemetry-propagator-ottrace` gem contains injectors and extractors for | Header Name | Description | Required | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -| `ot-tracer-traceid` | uint64 encoded as a string of 16 hex characters | yes | -| `ot-tracer-spanid` | uint64 encoded as a string of 16 hex characters | yes | +| `ot-tracer-traceid` | 64-bit; 16 hex digits (extract and inject) or 128-bit; 32 hex digits (extract) | yes | +| `ot-tracer-spanid` | 64-bit; 16 hex digits | yes | | `ot-tracer-sampled` | boolean or bit encoded as a string with the values `'true'`,`'false'`, `'1'`, or `'0'` | no | | `ot-baggage-*` | repeated string to string key-value baggage items; keys are prefixed with `ot-baggage-` and the corresponding value is the raw string. | if baggage is present | @@ -24,11 +24,15 @@ This issue was [fixed](https://github.com/open-telemetry/opentelemetry-go-contri ### Interop and trace ids -The OT trace propagation format expects trace ids to be 64-bits. In order to -interop with OpenTelemetry, trace ids need to be truncated to 64-bits before -sending them on the wire. When truncating, the least significant (right-most) -bits MUST be retained. For example, a trace id of -`3c3039f4d78d5c02ee8e3e41b17ce105` would be truncated to `ee8e3e41b17ce105`. +OTTrace was changed to be interoperable with other format so it is supposed to 8 or 16 byte array values for the trace-id. + +In order to do that Lightstep released a version of the OTTrace propagators in OpenTracing SDKs that left padded 64-bit headers to 128-bits using an additional 64-bit of 0s. + +The reality of the world is not every application upgraded to support 16 byte array propagation format, but this propagator must still convert legacy 64-bit trace ids to match the W3C Trace Context Trace ID 16 byte array. + +In addition to that it must be interoperable with legacy OTTracers, which expect 64-bit headers so this propagator truncates the value from a 128-bit to a 64-bit value before inject it into the carrier. + +This propagator is compatible with 64-bit or 128-bit trace ids when extracting the parent context, however it truncates the trace ids down to 64-bit trace ids when injecting the context. ### Baggage Notes