From 95bd888bff89c3607db94f7492b6d8bfd280d448 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Fri, 13 Apr 2018 11:28:32 -0700 Subject: [PATCH 1/3] mutating of trace state --- trace_context/HTTP_HEADER_FORMAT.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/trace_context/HTTP_HEADER_FORMAT.md b/trace_context/HTTP_HEADER_FORMAT.md index e1e1181e..b0f38db4 100644 --- a/trace_context/HTTP_HEADER_FORMAT.md +++ b/trace_context/HTTP_HEADER_FORMAT.md @@ -184,3 +184,16 @@ Multiple tracing systems (with different formatting): ``` tracestate: rojo=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01,congo=lZWRzIHRoNhcm5hbCBwbGVhc3VyZS4= ``` + +# Mutating the traceparent field + +## Base mutations + +Library or platform receiving `traceparent` request header MUST send it to outgoing requests. It MAY mutate the value of this header before passing to outgoing requests. + +Here is the list of allowed mutations: +1. **Update `span-id`**. The value of property `span-id` can be regenerated. +2. **Mark trace for sampling**. The value of `sampled` flag of `trace-options` may be set to `1` if it had value `0` before. `span-id` MUST be regenerated with the `sampled` flag update. +3. **Restarting trace**. All properties - `trace-id`, `span-id`, `trace-options` are regenerated. + +Libraries and platforms MUST NOT make any other mutations to the `traceparent` header. From 95793c1295758438435999a2bf43dd31fe1c4399 Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Tue, 17 Apr 2018 00:06:03 -0700 Subject: [PATCH 2/3] added examples for every mutation --- trace_context/HTTP_HEADER_FORMAT.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/trace_context/HTTP_HEADER_FORMAT.md b/trace_context/HTTP_HEADER_FORMAT.md index b0f38db4..8d67439c 100644 --- a/trace_context/HTTP_HEADER_FORMAT.md +++ b/trace_context/HTTP_HEADER_FORMAT.md @@ -189,11 +189,13 @@ tracestate: rojo=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01,congo=l ## Base mutations -Library or platform receiving `traceparent` request header MUST send it to outgoing requests. It MAY mutate the value of this header before passing to outgoing requests. +Library or platform receiving `traceparent` request header MUST send it to outgoing requests. It MAY mutate the value of this header before passing to outgoing requests. + +If the value of `traceparent` field wasn't changed before propagation - `tracestate` should also be propagated unmodified. Unmodified headers propagation is typically implemented in a pass-thru services like proxies. This behavior may also be implemented in a services which currently does not collect distributed tracing information. Here is the list of allowed mutations: -1. **Update `span-id`**. The value of property `span-id` can be regenerated. -2. **Mark trace for sampling**. The value of `sampled` flag of `trace-options` may be set to `1` if it had value `0` before. `span-id` MUST be regenerated with the `sampled` flag update. -3. **Restarting trace**. All properties - `trace-id`, `span-id`, `trace-options` are regenerated. +1. **Update `span-id`**. The value of property `span-id` can be regenerated. This is the most typical mutation and should be considered a default. +2. **Mark trace for sampling**. The value of `sampled` flag of `trace-options` may be set to `1` if it had value `0` before. `span-id` MUST be regenerated with the `sampled` flag update. This mutation typically happens to mark the importance of a current distributed trace collection. +3. **Restarting trace**. All properties - `trace-id`, `span-id`, `trace-options` are regenerated. This mutation is used in the services defined as a front gate into secure network and eliminates a potential denial of service attack surface. -Libraries and platforms MUST NOT make any other mutations to the `traceparent` header. +Libraries and platforms MUST NOT make any other mutations to the `traceparent` header. \ No newline at end of file From f0a46530fcec02322b01558382426bcdb897398b Mon Sep 17 00:00:00 2001 From: Sergey Kanzhelev Date: Tue, 17 Apr 2018 09:20:51 -0700 Subject: [PATCH 3/3] stronger language --- trace_context/HTTP_HEADER_FORMAT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trace_context/HTTP_HEADER_FORMAT.md b/trace_context/HTTP_HEADER_FORMAT.md index 8d67439c..cda68dbd 100644 --- a/trace_context/HTTP_HEADER_FORMAT.md +++ b/trace_context/HTTP_HEADER_FORMAT.md @@ -191,7 +191,7 @@ tracestate: rojo=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01,congo=l Library or platform receiving `traceparent` request header MUST send it to outgoing requests. It MAY mutate the value of this header before passing to outgoing requests. -If the value of `traceparent` field wasn't changed before propagation - `tracestate` should also be propagated unmodified. Unmodified headers propagation is typically implemented in a pass-thru services like proxies. This behavior may also be implemented in a services which currently does not collect distributed tracing information. +If the value of `traceparent` field wasn't changed before propagation - `tracestate` MUST NOT be modified as well. Unmodified headers propagation is typically implemented in a pass-thru services like proxies. This behavior may also be implemented in a services which currently does not collect distributed tracing information. Here is the list of allowed mutations: 1. **Update `span-id`**. The value of property `span-id` can be regenerated. This is the most typical mutation and should be considered a default.