Add description of TraceState operations

open-telemetry · Sep 1, 2020 · 8020382 · 8020382
1 parent 11ba3d8
commit 8020382
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 4 deletions.
diff --git a/specification/trace/api.md b/specification/trace/api.md
@@ -175,11 +175,10 @@ byte.
 TraceFlags are present in all traces. The current version of the specification
 only supports a single flag called [sampled](https://www.w3.org/TR/trace-context/#sampled-flag).
 
-`TraceState` carries system-specific configuration data, represented as a list
+`TraceState` carries vendor-specific trace identification data, represented as a list
 of key-value pairs. TraceState allows multiple tracing
-systems to participate in the same trace. Please review the [W3C
-specification](https://www.w3.org/TR/trace-context/#tracestate-header) for
-details on this field.
+systems to participate in the same trace. It is fully described in [W3C
+specification](https://www.w3.org/TR/trace-context/#tracestate-header).
 
 ### IsValid
 

diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md
@@ -195,6 +195,24 @@ Thus, the SDK specification defines sets of possible requirements for
   (for example, the `Span` could be one of the parameters passed to such a function,
   or a getter could be provided).
 
+## TraceState manipulation
+
+`TraceState` is a part of [`SpanContext`](../api.md#spancontext), represented by a list of key-values pairs and
+ formally defined by [W3C specification](https://www.w3.org/TR/trace-context/#tracestate-header).
+Tracing SDK MUST provide at least the following mutation operations on `TraceState`:
+
+* Update key value
+* Add a new key/value pair
+* Delete a key/value pair
+
+These operations MUST follow rules described in [W3C specification](https://www.w3.org/TR/trace-context/#mutating-the-tracestate-field).
+
+Please note, that as `SpanContext` is immutable, it is not possible to update `SpanContext` with a new `TraceState`.
+Such changes then make sense only right before 
+[`SpanContext` propagation](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/context/api-propagators.md) 
+or [telemetry data exporting](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/sdk.md#span-exporter).
+In both cases `Propagators` and `SpanExporters` may modify `TraceState` before serializing it to the wire.
+
 ## Span processor
 
 Span processor is an interface which allows hooks for span start and end method