Remove warnings about Span.UpdateName

[iNikem]

Fixes #468

Remove warnings against using Span.UpdateName. Adds notes about Samplers being unable to recalculate their decision after Span.UpdateName or Span.SetAttribute.

This PR somewhat duplicates #506 submitted by @toumorokoshi . I made new PR because that one gone stale and author does not answer.

Citing myself from #506 (comment)

Please, can we keep the scope of our discussion to the scope of this PR?

I support the opinion that we cannot remove Span.updateName completely, because doing that will make many instrumentations much more complicated. As was demonstrated several times both in this PR and in the related task, there are valid use-case where "good" span name is unknown until after span is created.

I don't think that span name differs in any way from any other span attribute from Sampler perspective. So if sampler deals somehow with attribute changes, it has to deal with span name change as well.

This comment from @c24t summarises it very nicely:

it's better for the spec to describe how implementations ought to be written than how users ought to use them. That is, if we provide an UpdateName API method the onus should be on the author of the sampler to explain that changes to the name won't affect the sampling decision, not on the user to know not to use that particular method.

For these reasons I think we have to merge this PR. As long as we have Span.updateName method in our API we should NOT discourage its usage. If later we decide to remove that method, that will be done in later and separately. Current PR does not depend on that future potential.

[yurishkuro]

I don't think this is accurate, especially given open-telemetry/oteps#115

[iNikem]

This reflects current state of the spec:

Sampler interface allows users to create custom samplers which will return a sampling SamplingResult based on information that is typically available just before the Span was created.

I cannot propose a PR to spec based on not yet merged OTEP, can I?

[yurishkuro]

Then why remove the warning? Until that OTEP is implemented, samplers cannot react to changes in the span name, can they?

[iNikem]

That was discussed at length in #506 . Span.updateName has legit use-cases and having this warning confuses people: "why have a method but discourage to use it?" We cannot remove the method, thus I propose to remove the warning.

[jmacd]

For me, the discussion in OTEP 115 clarifies that there are two distinct kinds of sampling decision. There is a head sampling decision that is irrevocable, made when the span starts, but this is only a provisional decision to begin gathering a span. There is still a tail sampling decision to be made that can incorporate new information, and we shouldn't mix terms and call these both a sampling decision.

This conversation appears to relate to the first decision, which practically by definition can't be changed because it's history by the time any new information arrives. I would just be clear that when we say "Sampler" (capital "S") we are referring to an initial decision that can't be revoked, not a final decision.

[iNikem]

I agree with that. And link here to "samplers" as defined in SDK spec. I can change "sampler" to "Samplers" if that will make it clearer :)

[iNikem]

Also, @yurishkuro , I would like to point your attention that this PR solves issue #468 which is triaged for GA and assigned P1. If you disagree with this, that issue would be a better place to try and change this decision.