UI should support generic and site-specific tags

[codefromthecrypt]

Feature:
Right now, the "annotation query" section is flexible by allowing people to enter free-form text. However, this is not ideal for some sites. It would be good to allow some tag names to be pre-populated with value auto-completion. Notably, things with low cardinality like the standard "http.route" or a site-specific "phase".

Rational
Sometimes people make mistakes in the UI search by using incorrect key/value encoding. Also, folks like LINE and also Expedia already know there is a need for pre-defined site specific tags. This was discussed at length at the LINE workshop, who made a new UI that supports this.

https://cwiki.apache.org/confluence/display/ZIPKIN/2018-10-29+Zipkin+UI+at+LINE+Tokyo

This was also previously discussed at Netflix who have some site-specific tags that help correlate with Spinnaker deployments: https://cwiki.apache.org/confluence/display/ZIPKIN/2018-07-18+Aggregation+and+Analysis+at+Netflix

Example Scenario
For example, LINE has a phase tag, which is similar to an environment. This allows the user to easily reduce results without thinking about search syntax or making mistakes.

Prior Art

• https://github.com/ExpediaDotCom/haystack-ui

[tacigar]

I think the first step is creating a new API for fetching annotations like the following.

• endpoint: /api/v2/annotations
• response format:

{
  "serviceName1": { "annotation1", "annotation2", "key1=value1", ... },
  "serviceName2": ...,
  ...
}

Of course, I think that it is good to fetch at the timing when the service name is changed, like span names.
However, since the default value of service name is all and I think that annotation query suggestion should be valid in this case, so I think that it is necessary to fetch annotations of all service names after all.
So I think fetching all annotations of all services at first is better.
After that, with the change of the service name as a trigger, we can filter these data at local.

[tacigar]

The second step is about UI, but I do not know the component library to do such functions well... 😢

[codefromthecrypt]

The second step is about UI, but since I do not know the library to express such functions well... 😢

you seem to express them in code well enough ;)

[codefromthecrypt]

as annotations are rarely used (the term annotation in annotationQuery is historical) For the purpose of dropdown I would suggest

/tags the response could indeed be broken down by service, but in this case the value is more simpler as a map per service name

ex

GET /api/v2/tags
["service": { "environment": "beta"}, "service2"  { "environment": "omicron"}]

Note that breaking down by service has pros and cons. Pro is that a very chatty service who abuses service names can be disabled (though that could also be done on the back end). Con is that there will be a lot of repetition, also a con is that pre-defined tag name/values will be a little more work to break down by service. Ex some sites may choose to limit the predefined key/value obviating a special api for it.

You'll notice haystack doesn't currently break down field query by service. They have an api to get the tag keys, and another to get values available for that key. It is a bit simpler, but yeah less insight into whether an auto-complete would succeed or not. https://github.com/ExpediaDotCom/haystack-idl/blob/419450f736634a5f4104998f471d478b632c8bfb/proto/api/traceReader.proto#L84

So, another option is just to return the same as they do or everything in one map. One problem with a big map is when people goof cardinality, the performance will suffer greatly I suspect. This is similar to why we have a separate api for service names and span names by service.

This leads to an api similar to our service name and span name, also similar to haystack, where you can do a query for tag keys, and another for values by key. Though since these are site defined, I would suggest the api return a friendly label for the key possibly (that or out-of-band config I guess..)

ex

GET /api/v2/tagKeys
{"environment": "Environment", "threat.level": "Maturity"}

GET /api/v2/tagValues?key=environment
["alpha", "beta", "omnicron"]

In general, data dynamics will be similar in nature to span names api. If we stick to that, we can take advantage of existing code and timeouts around "name queries" as querying for tags can be expensive in the same ways span names query are expensive.

Not all storage currently support a tags query not scoped by serviceName. In this case, maybe if we do make a special "all" reserved word, possibly it should not be returned in the case that the backend doesn't support it. I would vote for not differentiating by service thinking it through so far. Interested in other thoughts.

@openzipkin/core any thoughts? cc also @narayuna @drolando @cwensel from SF meetup

[tacigar]

I also read the haystack-ui code and I knew they had taken such an approach.
However, they did not seem to have a process to get values in the UI yet, though there is API for fetching values.
Probably now it is possible to suggest only serviceName and operationName in haystack-ui yet.
Sorry, this is another topic.

I have read your thoughts and my opinion has changed.
I agree with you.

[codefromthecrypt]

PS I reconsidered having the storage api return the human description for reasons including i18n.

Following is better. We can leave english (or japanese) description to UI assets and/or config.json

GET /api/v2/tagKeys
["environment", "threat.level"]

[codefromthecrypt]

https://cwiki.apache.org/confluence/display/ZIPKIN/Sites

@drolando @kristofa @narayaruna @anuraaga @jcarres-mdsol @zeagord @huydx @jonathan-lo @jcchavezs Can you all add a section to your site doc like below:

** Service Name
At XXX, we use the zipkin service name to represent XX. It is sourced from Y (environment, discovery, etc). We use it (only in zipkin, in correlation to a different system etc)

** Site-specific tags
The following are span tags we frequently use in indexing or aggregation

| Tag | Description | Usage |

[codefromthecrypt]

updated site-specific tag request to also explain how you use service name. cc also @narayaruna as originally I spelled your github user wrong :(

[codefromthecrypt]

update: I think we know a few things cc @openzipkin/core @openzipkin/ui

Here are some insights from looking at @anuraaga's site https://cwiki.apache.org/confluence/pages/viewpage.action?pageId=95655004

Site specific tags include both fixed and high cardinality tags

• Fixed would be indexed similar to service/span Adds Cassandra support for Autocomplete tags #2309 these will allow auto-complete. Ex plan-id is likely fixed
• High cardinality is only for things like auto-completing or reserving a search field names. For example, antennae-id is not likely fixed
• In any case, the UI would need overlay configuration to name the tags. Ex associating a friendly name and/or description with antennae-id. This could be done in /config.json which we can populate from spring configuration or even an environment variable.

[codefromthecrypt]

closed moving high-cardinality support to #2506