Add tracestate name registery

[wu-sheng]

Related to #58 , Provide vendor/open source product name register for "trace-state"

[codefromthecrypt]

I think something like this is two-fold: one is format and another is well-known-public-provider.

For example: aws might be referring to their format? It could also be referring to the public cloud itself.

It is worth considering. Also, I think the first format on the list should be equivalent to the traceparent maybe the label tc for native trace-context format.

[codefromthecrypt]

reason I use the amazon example is that early days "ec2" was both an api and also a public service. People started cloning the api. In the jclouds project, we had to come up with a way to describe the api separate from the provider of it. Incidentally we used the same registry for both. Ex "aws-ec2" was a provider of "ec2", but both labels were in the same registry for ease of use.

[wu-sheng]

@adriancole I just want to setup a registry for format, which relates to public service provider, vendor or project. And each on of them can choose a name and keep it public to else.

[wu-sheng]

@adriancole such as, if AWS support this sepc, their X-RAY need a tracestate name in value field. They should choose their own.

[SergeyKanzhelev]

so @wu-sheng you think to put entire header as described in the link as a trace state?

[wu-sheng]

@SergeyKanzhelev I think that could be optional, if this format is open. This maybe help people to diagnose interop issues.

[codefromthecrypt]

right. my comments were more about guidance on why this exists and what would be a reason it should be updated. I think we'll need some "intro section" in other words.

[codefromthecrypt]

fyi if we had such a registry, the table should point to the actual format.

basically as a developer or even a user, if I go to a table for a trace state entry, it should bring me exactly to the state definition... remember this? https://drive.google.com/drive/u/0/folders/0B0tSnQT3uGdAWU00QW1HQUFGeG8 (not sure you can see it)

[wu-sheng]

right. my comments were more about guidance on why this exists and what
would be a reason it should be updated. I think we'll need some "intro
section" in other words.

Maybe you are better than me to write this intro section. What do you think? I am afraid my English is not so native enough.

And format column added.

[codefromthecrypt]

@wu-sheng I'll happily add the intro section, by adding a commit to your branch. I'm going to wait until a couple others give feedback first.

[yurishkuro]

Do we still have an open question whether the labels should be just (vendor) or (vendor-site)?

[wu-sheng]

Do we still have an open question whether the labels should be just (vendor) or (vendor-site)?

@yurishkuro Do you mean the name:label=xxxxx,name:label2=yyyyy stuff? If so, I think we should discuss that in other thread

[yurishkuro]

I mean something like tracestate: jaeger:uber=xxxx, jaeger:redhat=yyyyy, i.e. same tracing library but different sites. The point is that if this is something we envision needing, then the public registry is less useful, or at least a bit premature.

[wu-sheng]

I think the label thing is for two isolated/independent but same tracing system monitoring the whole distributed tracing system. And the tracestate name registery is for different tracing system isolation.

e.g. You can use New Relic/Jaeger for monitoring a distributed system, OR, you can use two separated Jaegers to trace a distributed system.

So, in my perspective, they are different usage.

• tracestate name registery for vendor.
• label(or namespace in SkyWalking) for end user isolate two deployed system. Only should let end user known this thing, when they got into two tracing system, but same format. I understand that is more common for B3 format, because of Zipkin/Jaeger and other tracing system supported. But many more commercial product, AppDynamic, New Relic, etc have their own.

And another example, I think should put this in this way, because in Huawei cloud, we provide SkyWalking cloud service, which should be isolated with end user's own monitoring system(assume they use SkyWalking, just for example).
Or people used two cloud service instance(namespace) to monitor a distributed system.
This is where we use label/namespace. This is not a common scenario right?

[SergeyKanzhelev]

There are three reasons to have a registry. First is to claim a key. Second - document vendor specific tracestate. Third is to list some best practices for tracestate content. @wu-sheng which one is the most important for you?

I understand that is more common for B3 format, because of Zipkin/Jaeger and other tracing system supported. But many more commercial product, AppDynamic, New Relic, etc have their own.

The whole point of the standard is to make more systems act the same way. This is one of the reason @AloisReitbauer pushing to have a unified export format discussed as well. So you can build an APM product by importing spans from different systems. Yes, vendors might have specifics and extra features. Ideally though, basic behavior should be preserved when possible. So tracestate wouldn't be just a collection of all trace-related headers.

@yurishkuro I like the idea of labels. Specific of Application Insights is that it's optimized for high-tenancy model. Every application can be (and many times is) a separate tenant. ACL is a backend feature that decides which subset of applications one have access to. So (vendor-site) may be taken to the extreme here. I like the idea though.

[wu-sheng]

@SergeyKanzhelev I think claim a key is the most important. Don't like a conflict in real world.

The examples just show why I think registry is different with label, even they have similar effort. I agree with you , label should be used in somewhere like tenancy.

[AloisReitbauer]

Can someone please fix the English language here, so we can merge the PR

[wu-sheng]

Yes, please some native English guys help me on this.😃😃

[codefromthecrypt]

I like shipping things.. I think there are several points of concern mentioned based on usage patterns not actually defined in the text. The actual changes here only discuss a registry and claiming a label. There's no mention as to why apart from avoiding conflict.

We MUST have an example, to help pin this down.

If you want me (or someone else, but I'm fine) to clean up the english, I would say something like..

Each tracestate entry is a position within a trace. A trace can span multiple tracing systems, compatibly given common formats. The below registry of well-known labels allow participating parties to map a format to a tracestate entry. For example, the "b3" format includes a concatenation of data previously represented by headers prefixed with X-B3-.

This registry serves a secondary purpose, which is to reserve words for well-known public services. For example, the label "aws" might imply both a format and also a single trace namespace.

Personally, I think we MUST define format labels regardless of if we make a name claiming thing for public services. In other words, I might narrowly define this as format as that could lead to a quicker merge and we can still have a separate change to talk about name claiming for vendors.

When I get some guidance on this, happy to weave it in, or someone else can.

[wu-sheng]

Each tracestate entry is a position within a trace. A trace can span multiple tracing systems, compatibly given common formats. The below registry of well-known labels allow participating parties to map a format to a tracestate entry. For example, the "b3" format includes a concatenation of data previously represented by headers prefixed with X-B3-.

This registry serves a secondary purpose, which is to reserve words for well-known public services. For example, the label "aws" might imply both a format and also a single trace namespace.

I think this should make things clear. At least for me.

[codefromthecrypt]

Cleaned up wording

[wu-sheng]

@AloisReitbauer You can check this pr now. :) @SergeyKanzhelev @yurishkuro @bogdandrutu are you OK with this?

[yurishkuro]

As we discussed yesterday on the call, the suggestion is to close this PR and move the wording to an issue, for further discussion, because it seems premature to start maintaining the registry before the final agreement is reached about the semantics of the keys in the trace-state (i.e. is it a vendor name, or format name, or something + site name, etc.)

[AloisReitbauer]

@wu-sheng During the call we decided to close the PR and defer further decision for the next F2F meeting. Good with that?

[AloisReitbauer]

Moving the discussion back to the issue first.