Add a section for OTel specific values in TraceState.

[carlosalberto]

Related to open-telemetry/oteps#168 as we want to be able to specify OTel-specific values how in tracestate (in the case of the aforementioned OTEP, as we want to store probability and a random number, for sampling purposes).

This is a draft for now, in order to get OTEP 168 make progress.

cc @yurishkuro

[carlosalberto]

@yurishkuro Please review, as I've updated this PR based on your feedback ;)

[carlosalberto]

@yurishkuro @Oberon00 Updated the document to use the same notation used by the TraceContext specification. Specific changes:

1. Mentioned the entire list MUST NOT exceed 256 characters, as the related TraceContext's value section specifies.

2. Keys are limited to two characters, mostly being alphanumeric (p, rs or t1, for example). I think this will give OTel concerns enough range of sub-keys. Otherwise, happy to change it.

3. Values are limited to a-z / A-Z / 0-9 / "-" / "_" / "." - I think it makes sense to start with a small range of allowed characters, but have otherwise no opinion (will cc a few people who may know more).

4. Did NOT put a limit on the sub values, as choosing anything feels rather random - should it be 10? Should it be 6? Should it be 4? For now, I only mentioned again that 256 is the maximum length for the entire list.

cc @dyladan @mwear

[carlosalberto]

Hey @yurishkuro

Iterated and updated over this PR. Left a small note regarding SDKs being encouraged to discard a value update if it ends up exceeding the 256 char limit.

I would consider instead requiring API-only access, like SetInclusionProbabilityLog2(p). This may be a question for a different PR though

Agreed. Having such abstraction would be a good thing to have. I'd vow for specifying them in a follow up, once the foundation here is done (more specifically on the SetInclusionProbabilityLog2() operation (and such) operations, I imagine we defining them in their own concerns, way down the road).

A final note is that I feel now that this handling should be a SDK-wide part, more than a Trace one.

[carlosalberto]

I think that question should be addressed here, not there.

Agreed, let's do that here.

[carlosalberto]

Updated the PR to reflect the latest feedback:

• Mention that ONLY keys defined in the Specification should be used - instrumentation libraries and clients MUST use their own entry.
• Upon updates, no order needs to be preserved.

Question: Should we really go back to otel as the entry key?

[carlosalberto]

Ping @bogdandrutu - I think we are ready to go, unless you think there's something we need to tune still.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[carlosalberto]

Ping @Oberon00 @bogdandrutu - hopefully we can iterate on the remaining bits so this can be merged ;)

.