Add Span#addLink, for adding link after span start

[jack-berg]

Implementation of new spec requirement to support adding links after span start, defined in: open-telemetry/opentelemetry-specification#3678

[codecov]

Codecov Report

Attention: 9 lines in your changes are missing coverage. Please review.

Comparison is base (8684882) 91.06% compared to head (4588c3c) 91.01%.

Files	Patch %	Lines
.../main/java/io/opentelemetry/sdk/trace/SdkSpan.java	68.00%	4 Missing and 4 partials ⚠️
...emetry/extension/incubator/trace/ExtendedSpan.java	50.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main    #6084      +/-   ##
============================================
- Coverage     91.06%   91.01%   -0.05%     
- Complexity     5671     5676       +5     
============================================
  Files           620      621       +1     
  Lines         16553    16580      +27     
  Branches       1689     1693       +4     
============================================
+ Hits          15074    15091      +17     
- Misses          993      998       +5     
- Partials        486      491       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jack-berg]

@jkwatson any additional comments? Thanks!

[jkwatson]

🚢 tiny javadoc suggestion, but nothing major

[jack-berg]

@jkwatson I was about to merge but double checked the stability status of the addLink and saw that it was experimental! So I refactored this PR a bit to move it to the incubating module instead.

[breedx-splk]

Looks good overall, but had a couple of ideas about the interface.

[breedx-splk]

Something about this gives me pause -- because it is implementing two interfaces both of which extend a common parent interface. Seems weird to me. Maybe it's nothing, but it seems like a smell to me.

Immediately makes me question whether or not ExtendedSpan really needs to extend Span.

[jack-berg]

Initially I switched ReadWriteSpan to extend ExtendedSpan instead of Span, but that doesn't work because ReadWriteSpan is part of the public API, and we can't have experimental surface area exposed in the stable API.

We have a long history of doing non-ideal things to be able to incubate things without committing to the stable API. While this is a smell, it will be short lived as it goes away as soon as the spec stabilizes and these methods are promoted to span.

Immediately makes me question whether or not ExtendedSpan really needs to extend Span.

Any other ideas?

[trask]

We have a long history of doing non-ideal things to be able to incubate things without committing to the stable API.

👍

[breedx-splk]

Immediately makes me question whether or not ExtendedSpan really needs to extend Span.

Any other ideas?

What if it just didn't? It can be its own stand-alone interface, right? And it's only used by the single implementation.

[jack-berg]

Well the idea is that a user casts spans to ExtendedSpan to access the the combination of stable and experimental methods:

ExtendedSpan span = (ExtendedSpan) tracer.spanBuilder("name").startSpan();
span.setAttribute("key", "value");
span.addLink(spanContext);

If ExtenedSpan doesn't extend Span, then its more awkward to use:

Span span = tracer.spanBuilder("name").startSpan();
span.setAttribute("key", "value");
// Cast span to ExtendedSpan just to access #addLink
((ExtendedSpan) span).addLink(spanContext);

[breedx-splk]

Yeah ok, I get it. Thanks for clarifying.