Opentelemetry-specification: Rename span.end() to span.finish()

[yurishkuro]

This is likely controversial and late in the game. In the spec/PRs everyone tends to write "when span is finished", because "when span is ended" sounds odd. Can we consider renaming this method?

I already got +1 from @carlosalberto :-) (https://github.com/open-telemetry/opentelemetry-specification/pull/485#discussion_r391171105)

[fbogsany]

Ruby already calls it finish, so 👍 from the Ruby SIG: https://github.com/open-telemetry/opentelemetry-ruby/blob/7f583df9b48a78a08c2dfb742f73287f59721f3b/api/lib/opentelemetry/trace/span.rb#L138

[dyladan]

This seems late for something so trivial with such a large impact. Why is ruby's implementation different from all others?

[mwear]

end is a keyword in Ruby. We could technically use it as a method name, but finish is a better solution.

[yurishkuro]

@dyladan it is indeed late, but I think given the existing scope of APIs/SDKs, none of which are yet officially in beta, I don't think this is insurmountable. The change itself is likely going to be trivial to apply.

[MikeGoldsmith]

I also prefer Finish over End. It feels like a more natural noun to use for me.

[Oberon00]

So if we rename this, what about #318? We can take this opportunity to also rename Span to TelemetrySpan or TracedOperation, etc.

[yurishkuro]

Renaming end to finish has a clear value proposition. #318 is much more murky and very much language-dependent. I would not conflate these two tickets.

[Oberon00]

Renaming end to finish has a clear value proposition

More clear than #318?

318 is much more murky and very much language-dependent

How so?
An argument for this issue was even the language-dependent issue that ruby cannot use end. So personally I think the value proposition of #318 is more clear. 😃

Personally, I'm weakly against both the renamings suggested here and in #318.

[jmacd]

I am in favor of this renaming, but "finish" is not a 100% clear winner to me. All of the terms "stop", "done", "end", and "finish" are viable in this context, and there are so many uses of these words in English that I'm not sure which is most common, but then I had a memory.

My high school German teacher had a saying, whenever a student said "I'm done." she would repeat "The roast is done, you're finished." I believe she would support this proposal.

I have noticed, like @yurishkuro, that in our technical discussion that we also use "finish" in the verb sense most often. I used this kind of argument to rename "Cumulative" to "Counter" in the Metrics API.

Grammar nerds and non-english speakers are likely to be familiar with the distinction between transitive and intransitive verbs. Both "end" and "finish" are used as verbs, and in colloquial usager both can be used transitively or intransitively. (e.g., "I will end this debate", "I will finish this specification" are transitives, or "The beta period ended", "I finished"). Of the _intransitive_ uses (where there is no object), "finish" is the more common usage (as my teacher would say).

In a programming context, when we write

span.Finish()

or

span.End()

I think of these as intransitive uses. The span is the subject and the verb has no object. The span is finishing itself, not the span is finishing _something_.

I recognize that we have a situation where OpenCensus chose End and OpenTracing chose Finish, so we may not be able to resolve this.

[Oberon00]

These are all good arguments for why we finish is a better name than end. But I think both are sufficiently clear for everyone. I haven't heard a single complaint about the name end before. Yet, renaming this is a huge breaking change for everyone using the tracing API. If we want to give OpenTelemetry the reputation of a stable software project, then I would stay away from this change.

[Oberon00]

Another, weaker, argument I can make is that one could confuse a "finished" Span with one that finished going through the whole pipeline Span API -> Span processor -> Exporter (which can happen asynchronously at some point after end is called).
You could see end as telling the span that the associated operation has ended. The operation might not necessarily be finished (succesfully) but it has ended in some way.

[jmacd]

The fact that end is a reserved keyword in some languages is a point in favor of the renaming.

[pauldraper]

The pairs are usually start/finish (e.g. a race) and begin/end (e.g. SQL transaction).

[yurishkuro]

I added this to the next Spec SIG meeting's agenda

[Oberon00]

I think the important question is not whether "start" or "finish" is better, but whether the advantages of renaming this outweigh the cost of this breaking change.

I think the disadvantages are bigger here. Even when you don't factor in the cost of doing the renaming in all the repos in the open-telemetry org (including READMEs that are never compiled, etc), somebody out there might actually be (gasp!) using this software, and my guess is that they would be quite annoyed when they have to follow this renaming.

[yurishkuro]

True, but it can be done in backwards compatible way by marking end() as deprecated and not to survive v1.0

[dyladan]

I'm with @Oberon00 here. Any change _can_ be done, but the value of this particular change is so marginal that I don't agree it is worth the burden on users.

[Oberon00]

@yurishkuro That's not exactly what I would call backwards-compatible. It just moves the breaking change into the future and adds additional maintenance overhead for opentelemetry in the meantime.

[carlosalberto]

IIRC it was decided it's too late to change this.