Standard tag for adding a span title to tracer displays

[tedsuo]

Currently, Operation Name does double duty: first as a primary index/category for capturing statistical information about traces, and second as the primary label displayed on spans in trace viewers. Often this is fine, but sometimes these needs diverge, and users end up digging through span tags in order to get a sense of the overall trace, which can be awkward.

A classic example is a url path, which can greatly increase the readability of some traces but has a cardinality which is too high to be used as an operation name. A tag, such as span.title, could be used to indicate what should be displayed in cases where the operation name is insufficient but cannot be changed.

Is this a widespread enough issue that OT users and tracer implementors would like to adopt it as a standard? Do any tracers currently support something like this, or have an alternate approach for handling these cases?

[cwe1ss]

How does https://github.com/opentracing/specification/issues/72 relate to this in your opinion?

[pavolloffay]

Do you have any example of such a tag? Is it only for displaying/UI? Tracer's UI could derive this value based on all provided tags. e.g. if it is a database query show part of the statement, if it is HTTP show verb, part of the path and return code...

[tedsuo]

@cwe1ss this is purely for display so it's it's like the opposite of #72 which is about indexing. There is currently no affordance which allows you to describe a span, free of some other purpose or constrain.

@pavolloffay yes, this would be a tag just for display. The question is, do we need such a tag as an escape hatch when you can't get the display you want out of the standard tags. It's entirely possible that the standard tags will lead to sufficient display affordances as tracer UI's adopt them that the edge cases are minimal enough that no one cares.

If there isn't a resounding "yes I have been wanting that" from OT users and "yes I would implement that" from tracer implementors then I will close this issue and bring it up again later if more customers begin asking for it. I've had requests for this but it's not clear how wide spread the interest really is.

[pavolloffay]

Thanks for a clarification, my concern is that this tag does not add much value and may add data redundancy/overlap. Maybe a reasonable set of examples would help and also how this could be used in instrumentations.

If there isn't a resounding "yes I have been wanting that" from OT users and "yes I would implement that"

that is expected from OSS project :). I'm for keeping issues open until it is proven that it is nonsense.

[wu-sheng]

-1 on this. IMO, display tag may be not very useful. It is a tag about UI, which OT doen't concern. The url and sql-like(/UserTable/Select/ById) operationName is good enough, iff UI want to do better, they can provide operationName and custom tag mapping to the display name.

[mabn]

I can't come up with a good example where this would be needed.

I'd rather have the ability to create "formatters" in the UI which would extract data from specified tags and output some String and it would probably cover the case of span.title. It would generate less data (probably span.title value could be constructed from other tags anyway).

[RaduBerinde]

An example in CockroachDB is that a large operation might span many "ranges" (pieces of key-value space). At the level of each range there is a Batch operation; a big trace might have hundreds of Batch spans. It would be helpful to include the range ID in the title - otherwise if you are concerned about a particular range you have to open up all the spans to see more information. If you include it in the operation name, this becomes too fine grained for dashboards/statistics.

Like a few pointed out, this can be left entirely to the opentracing implementation. But it would be beneficial to standardize the approach so that the result is similar across different implementations.

[wu-sheng]

@RaduBerinde Your scenario like other database span. The rangeID should be part of operationName, for sure. If a tracer UI want to implement your requirement, it can provide a span sub-title configuration, which can set several tags as part of it. By doing this, you can see the rangeID or sql-statement in the trace page, no need to open up all the spans, one by one.

[RaduBerinde]

Yes but then they become separate operations and I can't plot stats for all Batch spans, which is useful.

[StephenWithPH]

We're also considering problems where

the operation name is insufficient... .

In our case, it's closely related to service names. Many different services may have a cache-get operation; discriminating among each service would be nice.

Several of the existing OT-compatible tracers make service name a first-class item. See:

• https://github.com/openzipkin/zipkin-go-opentracing/blob/master/zipkin-recorder.go#L71
• https://github.com/uber/jaeger-client-go/blob/master/tracer.go#L71
• https://github.com/instana/golang-sensor/blob/master/options.go#L6
• https://github.com/hawkular/hawkular-apm-opentracing-javascript/blob/master/lib/deployment-meta-data.js#L28

Yes, this need is largely driven by UI considerations, but "which service?" is a valid question.

Initially, I would have said this is a primary property of a span (i.e., adjacent to operation name). Upon further reflection, I think this can be a suggested tag. That avoids dirtying the core span fields for implementations that don't care about anything more than operation name.

Regarding official guidance on the name of the additional, standard tag:

• serviceName or span.service is easy and fits with some of the existing implementations
• span.source or span.group is a little more generic (maybe too much), but may better meet @RaduBerinde's use case

Note that my comments have some commonality with this closed issue: https://github.com/opentracing/specification/issues/58.

I'd love to hear thoughts on this.

[yurishkuro]

@StephenWithPH as you mentioned, service name is usually already captured during tracer initialization. Is it not sufficient?

[StephenWithPH]

@yurishkuro Once the tracer knows service name, where on the span should the tracer/recorder indicate that service name? In other words, where on the span itself should we indicate which service owns that span?

Perhaps this is implicitly getting tangled into the "single-sided span vs. shared span" question; I see that some of the peer tags could do nicely for shared RPC spans.

In our case, we're recording (single-sided) spans as-is to stdout. A different process maps that span to a given backend.

The specific implementations in my links above show a mixture of behaviors: they record the name either in a backend-specific custom location (e.g., Zipkin), a tag, or an additional top-level field of the span.

I see some utility in harmonizing this need (as soft guidance) in the OT spec. It's possible that a generic solution could meet this need along with some of the needs earlier in this thread.

Alternatively, I'm happy to carve this out into a different conversation to avoid hijacking @tedsuo's initial need.

[yurishkuro]

Alternatively, I'm happy to carve this out into a different conversation to avoid hijacking @tedsuo's initial need.

yes, let's not mix it in here.

[tedsuo]

@StephenWithPH @yurishkuro yeah that is separate but we also do the same at LightStep. We set the lightstep.component tag to mean "service/tracer", which was then poached by the official component tag, which means something else. So we would also like an official tag for this. Otherwise we will change our tag to service only to have that get poached to mean something else...

For this thread, the item under discussion is a tag, such as span.title or span.description, that specifically has no other meaning, so it can be safely used to add descriptive information without also affecting indexing or running into a semantic bikeshed.

Of course, you can already do this. But because it isn't a standard tag, tracers will not display it prominently. Alternatively, as tracers mature and develop UI formatters, and meaningful standard tags become integrated into displays effectively, this problem may go away. In @RaduBerinde's case, they already have the information they want in other tags, so their problem could be solved with UI formatters, or more standardization around the tagging of batch operations. Personally, right now it looks like the need is too marginal, and I would want to see examples of people using things like span.description on their own before making it official.

My only other :two_cents: at this juncture is to point out that the overhead of recording something like span.title (in addition to all the other tags and logs) is marginal, so it's a red herring to argue that this should be disallowed due to the collection overhead.

[yurishkuro]

My argument against span.title would be that it decentralizes a function that is best centralized in the UI. Instrumentation is hard to change, in some cases you don't even have access to it, I would rather have the flexibility in the UI to come up with the best visual representation. This is essentially the argument about structured vs. unstructured logging.

As for the service name, I may be think, but I am not seeing what the problem is. In Jaeger we use the term "service name" to describe the process (aka microservice) that uses an instance of a tracer. It's not a span-level information, but process-level, so there is no need for a span tag, we capture it as a "tracer-level tag" if you will. If the need here is to identify the logical service, e.g. a single process combines multiple logical services, then yes, a service tag makes sense, and it would be different from the tracer-level tag that describes the process (a deployment unit).

[StephenWithPH]

@yurishkuro @tedsuo ... any objections if I open new issue to continue our thread? I acknowledge that we're basically revisiting https://github.com/opentracing/specification/issues/58.

[tedsuo]

Thanks @StephenWithPH.

Thanks everyone for responding! I opened this thread to gauge the temperature on using a tag for display purposes. My takeaway is that instead of adding a display tag, one should:

• Add any missing information to spans as structured data, not as text descriptions.
• Help improve your tracer UI of choice if it cannot display your structured data sufficiently.

I am closing this issue for now. If someone wishes to propose something similar in the future, please make a new issue and reference this one.