Split SpanContext into interface / impl #1935

anuraaga · 2020-10-30T05:33:23Z

As enabled by open-telemetry/opentelemetry-specification#969

codecov · 2020-10-30T05:42:23Z

Codecov Report

Merging #1935 (09df67d) into master (49b3e68) will decrease coverage by 0.04%.
The diff coverage is 77.77%.

@@             Coverage Diff              @@
##             master    #1935      +/-   ##
============================================
- Coverage     85.04%   85.00%   -0.05%     
  Complexity     2170     2170              
============================================
  Files           246      247       +1     
  Lines          8318     8320       +2     
  Branches        924      924              
============================================
- Hits           7074     7072       -2     
- Misses          907      910       +3     
- Partials        337      338       +1

Impacted Files	Coverage Δ	Complexity Δ
...n/java/io/opentelemetry/api/trace/SpanContext.java	`77.77% <66.66%> (-11.70%)`	`9.00 <6.00> (-5.00)`
.../opentelemetry/api/trace/ImmutableSpanContext.java	`83.33% <83.33%> (ø)`	`5.00 <5.00> (?)`
...try/sdk/metrics/aggregator/LongMinMaxSumCount.java	`95.91% <0.00%> (-4.09%)`	`6.00% <0.00%> (ø%)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 49b3e68...09df67d. Read the comment docs.

Oberon00 · 2020-10-30T08:12:42Z

This seems to make the code more complicated and arguably does not implement the "SHOULD" in "The API MUST implement methods to create a SpanContext. These methods SHOULD be the only way to create a SpanContext." since you can now create a SpanContext by deriving from the interface and instantiate the derived class.
So can you please state the reasons for these changes here?

Oberon00 · 2020-10-30T08:14:17Z

api/src/main/java/io/opentelemetry/api/trace/ImmutableSpanContext.java

+
+@Immutable
+@AutoValue
+abstract class ImmutableSpanContext implements SpanContext {


Since the interface is also annotated @Immutable and according to the spec any SpanContext must be Immutable, this is maybe not the best name to distinguish it from possible other implementations which would also be Immutable. Maybe DefaultSpanContext?

Yeah I had the same impression - we have Immutable* as a pattern in many AutoValue implementations of interfaces currently. Renaming them all to Default seems fine to me, or even *Impl so the implementation orders next to the interface in the filetree.

No strong opinion. I'd keep this name for this PR, and we can always rename later, since this is an internal detail.

anuraaga · 2020-10-30T08:31:49Z

@Oberon00 Weren't all the reasons in the long discussion in open-telemetry/opentelemetry-specification#969 and open-telemetry/opentelemetry-specification#970 ? :-) The short answer is for agent users, it will always be the agent's version of the API, not the user's version of the API, that instantiates a SpanContext. I thought we agreed this is ok in that issue.

Also one point of note is that we don't lose any protection with this PR since it's already an abstract class. Of course, we could stop using AutoValue to prevent that, just an observation. With #1937 I am thinking of a general question on whether we should just avoid classes at all in the API - it's an API after all. If a custom SDK (which our auto instrumentation agent effectively is) finds a reason to override the implementation and satisfies a use case with it, why block it?

Oberon00 · 2020-10-30T08:48:09Z

I suspected as much 😃 But I thought it was better to document it on the PR that does the change.

So the interface makes it even easier for the auto-instrumentation than the previous abstract class?

anuraaga · 2020-10-30T08:51:49Z

@Oberon00 Yeah - one class can implement both the agent (shaded) API interface and application API interface, but with abstract classes we wouldn't be able to do that so end up copying between two classes instead.

jkwatson

If it helps auto-instrumentation and doesn't hurt the end-user experience, I'm all in favor.

tylerbenson · 2020-10-30T16:54:14Z

api/src/main/java/io/opentelemetry/api/trace/SpanContext.java

@@ -17,23 +15,15 @@
 * traceState} and the {@link boolean remote} flag.
 */
 @Immutable


Does this still make sense on an interface?

I think it does. It places an requirement on all implementers and offers guarantees to users.

Obviously, it's a soft requirement, since it can't be enforced, but I still think it's a good thing to document.

bogdandrutu

Blocked until #1946

api/src/main/java/io/opentelemetry/api/trace/ImmutableSpanContext.java

jkwatson · 2020-11-01T02:21:55Z

After further thinking, I'd prefer SpanContext stay not as an interface, but as a final class (or AutoValue'd class). It's a core piece of data for the API, and since it's data-only, having it be non-interface is preferable to me.

jkwatson

Thanks!

trask · 2020-11-24T19:27:09Z

@bogdandrutu can you unblock this PR, or comment on #1946 which you blocked this on?

jkwatson · 2020-11-24T22:24:55Z

After further thinking, I'd prefer SpanContext stay not as an interface, but as a final class (or AutoValue'd class). It's a core piece of data for the API, and since it's data-only, having it be non-interface is preferable to me.

Note: although I usually favor data-as-classes, I'm on board with this change.

bogdandrutu · 2020-11-25T16:14:16Z

api/src/main/java/io/opentelemetry/api/trace/SpanContext.java

+  default boolean isValid() {
+    return TraceId.isValid(getTraceIdAsHexString()) && SpanId.isValid(getSpanIdAsHexString());
  }


this will become more expensive after this change, we should calculate this only once since it is used couple of times per instance created.

Also, see above...this is still memoized by the implementation.

bogdandrutu · 2020-11-25T16:15:42Z

api/src/main/java/io/opentelemetry/api/trace/SpanContext.java

+  default byte[] getSpanIdBytes() {
+    return SpanId.bytesFromHex(getSpanIdAsHexString(), 0);
  }


Why removing the ability to memoized this call? It may get expensive. I would suggest to not default this and any method that was memoized before.

This is still memoized by the autovalue implementation. See ImmutableSpanContext above.

bogdandrutu · 2020-11-25T16:23:30Z

My concern still stays on a general level. If there was no auto-instrumentation project majority of the engineers have implemented this as a final class, so I am concerned that we do designed choices based on an external project need that may influence the overall usability and performance of the core product. This designed choices may affect us in the future in an unknown way.

I do understand the needs coming from auto-instrumentation, but you need to keep in mind that right now we need to be prepared to deal with cases where users will implement this in a "unexpected" way like having mutable objects inside the SpanContext, etc. this may cause problems for us, and we may have to deal with this.

@jkwatson

Discussed with @jkwatson, we will add a note about not supporting alternative implementations

… into spancontext-interface

anuraaga · 2020-12-01T08:57:39Z

Thanks! Added a warning

jkwatson · 2020-12-01T19:06:09Z

@marcingrzejszczak this is potentially a breaking change

Split SpanContext into interface / impl

8cab661

anuraaga requested review from arminru, bogdandrutu, carlosalberto, jkwatson, pavolloffay, thisthat and tylerbenson as code owners October 30, 2020 05:33

Remove javadoc from impl to reduce drift change.

8c2b643

Oberon00 reviewed Oct 30, 2020

View reviewed changes

jkwatson approved these changes Oct 30, 2020

View reviewed changes

tylerbenson approved these changes Oct 30, 2020

View reviewed changes

tylerbenson mentioned this pull request Oct 30, 2020

Allow subclassing SpanContext by other packages #1940

Closed

tylerbenson reviewed Oct 30, 2020

View reviewed changes

This was referenced Oct 30, 2020

Replace AutoValue usage in baggage with final concrete classes. #1937

Closed

Initial list of best practices to follow in our project #1925

Merged

anuraaga mentioned this pull request Oct 31, 2020

Only expose interfaces in API #1946

Closed

bogdandrutu previously requested changes Oct 31, 2020

View reviewed changes

api/src/main/java/io/opentelemetry/api/trace/ImmutableSpanContext.java Show resolved Hide resolved

jkwatson self-requested a review November 2, 2020 16:46

jkwatson approved these changes Nov 20, 2020

View reviewed changes

trask approved these changes Nov 20, 2020

View reviewed changes

bogdandrutu reviewed Nov 25, 2020

View reviewed changes

Anuraag Agrawal added 3 commits December 1, 2020 17:55

Merge branch 'master' of github.com:open-telemetry/opentelemetry-java…

40b884b

… into spancontext-interface

Add warning

3109e68

More

09df67d

jkwatson merged commit 0163a8c into open-telemetry:master Dec 1, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Split SpanContext into interface / impl #1935

Split SpanContext into interface / impl #1935

anuraaga commented Oct 30, 2020

codecov bot commented Oct 30, 2020 •

edited

Loading

Oberon00 commented Oct 30, 2020

Oberon00 Oct 30, 2020

anuraaga Oct 30, 2020

jkwatson Oct 30, 2020

anuraaga commented Oct 30, 2020

Oberon00 commented Oct 30, 2020

anuraaga commented Oct 30, 2020 •

edited

Loading

jkwatson left a comment

tylerbenson Oct 30, 2020

Oberon00 Oct 30, 2020

jkwatson Oct 30, 2020

bogdandrutu left a comment

jkwatson commented Nov 1, 2020

jkwatson left a comment

trask commented Nov 24, 2020

jkwatson commented Nov 24, 2020

bogdandrutu Nov 25, 2020

jkwatson Nov 25, 2020

bogdandrutu Nov 25, 2020

jkwatson Nov 25, 2020

bogdandrutu commented Nov 25, 2020

anuraaga commented Dec 1, 2020

jkwatson commented Dec 1, 2020

Split SpanContext into interface / impl #1935

Split SpanContext into interface / impl #1935

Conversation

anuraaga commented Oct 30, 2020

codecov bot commented Oct 30, 2020 • edited Loading

Codecov Report

Oberon00 commented Oct 30, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anuraaga commented Oct 30, 2020

Oberon00 commented Oct 30, 2020

anuraaga commented Oct 30, 2020 • edited Loading

jkwatson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bogdandrutu left a comment

Choose a reason for hiding this comment

jkwatson commented Nov 1, 2020

jkwatson left a comment

Choose a reason for hiding this comment

trask commented Nov 24, 2020

jkwatson commented Nov 24, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bogdandrutu commented Nov 25, 2020

anuraaga commented Dec 1, 2020

jkwatson commented Dec 1, 2020

codecov bot commented Oct 30, 2020 •

edited

Loading

anuraaga commented Oct 30, 2020 •

edited

Loading