Clarify span name criteria (resolves #557).

[Oberon00]

Resolves #557.

Rationale

(quoted from #810 (comment))

1. Why a guideline at all? It streamlines discussion and avoids inconsistencies. For example, it would decide HTTP span name: Recommend handler over route name #548. There does not need to be a trade-off with human-readability here, since we could have both if we really wanted (see next point).
2. Why not prefer human-readability? Because a good display name can be synthesized without much trouble on the backend. This argument was one of the main reasons for declining And semantic conventions for Display Hints #730 (see And semantic conventions for Display Hints #730 (comment) by @yurishkuro) and I think it is a sound argument. On the other hand, a grouping key can be utilized for agent-side sampling (e.g. have a sampler that is rate-limiting per span name).

Changes

• Clarifies that generality of the span name is more important than human-readability.

[iNikem]

I strongly oppose the removal of "human readable" from the span name definition. This may lead to using hash-code, hexadecimals or whatnot as span name. Which I think is undesirable.

I do agree with added sentence at the end:

While a human-readable span name can be useful, one SHOULD NOT compromise
on the generality of the span name to improve human-readability

[Oberon00]

Agreed, I went a bit too far here with my rewording. I hope it's better with f7e714d.

[jmacd]

I see a contradiction here. get_user/314159 may be a statistically interesting class of spans (the requirement above), but high-cardinality is the rationale given below.

When I first read the (statistically) above, my eyes substituted the word statically, which may be a better way to write the specification. We reject get_user/314159 because it is implied to be a variable. My favorite way to address this is the way the Metrics API does: by requiring an "instrument".

Discussed here #734 (comment).

[Oberon00]

I don't see a contradiction. It says "the most general string". While "get_user/314159 may be a statistically interesting class of spans" it is certainly less general than get_user, which still an interesting class of of spans.

[jmacd]

I see your point. Maybe instead of "high-cardinality" you could write "too specific", i.e., something that that's opposed to the "general" quality.

[iNikem]

@Oberon00 Do I understand you correctly, that you want to say: "when making trade-off between span name being good grouping key and span name being good display name, choose the grouping key side"?

[Oberon00]

@iNikem Correct. These are the reasons I think this is good:

1. Why a guideline at all? It streamlines discussion and avoids inconsistencies. For example, it would decide HTTP span name: Recommend handler over route name #548. There does not need to be a trade-off with human-readability here, since we could have both if we really wanted (see next point).
2. Why not prefer human-readability? Because a good display name can be synthesized without much trouble on the backend. This argument was one of the main reasons for declining And semantic conventions for Display Hints #730 (see And semantic conventions for Display Hints #730 (comment) by @yurishkuro) and I think it is a sound argument. On the other hand, a grouping key can be utilized for agent-side sampling (e.g. have a sampler that is rate-limiting per span name).

[Oberon00]

In light of this, I wonder if I should revert f7e714d again to de-emphasize human-readability even more.

[iNikem]

In light of this, I wonder if I should revert f7e714d again to de-emphasize human-readability even more.

I don't think so :) IMO span name should (or even must) be human readable (as in "not a byte array"). But there is a huge difference in human readability between e.g. message on the coffee machine display and its user manual :) Both are readable, but trade-offs are different. And we should offer guidelines about trade-offs.

[Oberon00]

@iNikem OK, I won't revert it then 😃 If you are satisfied with this PR, would you please review it?

[SergeyKanzhelev]

I agree. This is a tradeoff we are taking in OpenTelemetry.

[SergeyKanzhelev]

@Oberon00 it may be out of the scope of this PR, but since you reinforcing the tradeoff we are taking in OpenTelemetry, you can also mention in this paragraph that the UpdateName may be used if the name collected automatically is too generic?

[cxhansen]

I think this is a good improvement to the wording. +1 on managing cardinality of span name.

[Oberon00]

@SergeyKanzhelev I think it would be best if you made that PR yourself, as I'm not completely sure I understand what you mean and this is a rather subtle topic.

[SergeyKanzhelev]

Enough approvals and cool off period passed. Merging