Add description of TraceState operations

[iNikem]

Fixes #759

Changes

Add description of TraceState operations.

Points of W3C-validation need to be decided, #905 (comment)

[SergeyKanzhelev]

This PR is LGTM overall. Marking as "Request changes" to finish feedback from @Oberon00 and @reyang:

• clarify implementeablity (are operations implemented in SDK or API).
• add a wording on strict operations.

[Oberon00]

Note that as @anuraaga suggested in #875 (comment) an alternative design would be to replace TraceState with a Map<Key<T>, T>. This could have multiple advantages:

• W3C tracestate could be stored as a single string under one key on that map.
• Custom propagators (also W3C-based) and samplers after SDK: Samplers should be able to modify tracestate #856 would be able to parse certain values out of W3C tracestate or other sources (including newly generated, e.g. random numbers for routing) and put them under specific keys to avoid re-parsing a tracestate (entry) every time the information is needed.
• Consider using Context as the unique way to specify parenthood #510 would become less a pressing issue.

[iNikem]

It may be so, indeed.

To avoid confusion: I still think this PR is useful for clarifying current state of the API and should be merged. I doubt we decide on removing TraceState completely very soon :)

[Oberon00]

The alternative approach would not be removing TraceState, it would just move it from a first-class member of SpanContext to being implemented with that more generic Map<Key<T>, T>. But that should also be doable later as a non-breaking change (given a careful implementation of TraceState).

[SergeyKanzhelev]

I think this PR makes things better. Switching to map may be a separate discussion. The worst things about the map is that it is looses the order which is critical for the specification. This is why I wouldn't suggest to jump into this discussion in this PR

[SergeyKanzhelev]

@iNikem I will let this PR sit for some time for cool off period for new comments. Otherwise it looks good and will be merged if not objections received by tomorrow PT

[Oberon00]

The worst things about the map is that it is looses the order

There are ordered maps, but my suggestion would anyway be to have the current W3C tracestate as a single unparsed string under a single key in that map.

This is why I wouldn't suggest to jump into this discussion in this PR

Right, this discussion is already going on at #875 (comment)

[iNikem]

@SergeyKanzhelev can we merge? :)