Opentelemetry-java: Move opentelemetry-api to io.opentelemetry.api package

[anuraaga]

Right now the OTel API is housed in io.opentelemetry package. We could move it to io.opentelemetry.api. This

• Makes it a bit more explicit in the package name that this is the OpenTelemetry API, as opposed to some OpenTelemetry helper
• Makes auto instrumentation much less fragile by having a single Java package prefix to handle specially with regards to shading. Currently, all classes in io.opentelemetry have to be handled specially since the io.opentelemetry prefix contains the world, not just the OpenTelemetry API
• Seems to have no real downside (other than a ton of work for me when updating the agent since our tests use Groovy 😿 )

[jkwatson]

I don't have a strong opinion on this, but if it makes things a bit easier for the instrumentation project then I'm fine with it. We need to do it quickly if we're going to do it at all, IMO.

[Oberon00]

I am weakly against this: having api in the package name might make users think "hmm, I don't need to re-implement the api but I want to use the SDK, so I'm using the sdk's TracerProvider". I think api might sound like a package only needed for advanced uses.

[anuraaga]

@trask What do you think?

[trask]

This would make our shading story much cleaner, which would also help our "custom distro" story, which relies on shading too.

I think it's a nice change regardless, as we talk about API vs SDK a lot, so nice to have this explicitly encoded in the package structure.

To @Oberon00's point, I think getting rid of OpenTelemetrySdk would help make the sdk less "discoverable", and help funnel people to the more obvious OpenTelemetry.get().

[iNikem]

I am weakly against this: having api in the package name might make users think "hmm, I don't need to re-implement the api but I want to use the SDK, so I'm using the sdk's TracerProvider". I think api might sound like a package only needed for advanced uses.

Since when sdk sounds like being for casual users and api for advanced users? I think we talk very much about api being the most common point of contact of users with Otel.

[Oberon00]

sdk does not necessarily sound more casual, but just opentelemetry.trace.Span sounds more casual that openelemetry.api.trace.Span.

[iNikem]

sdk does not necessarily sound more casual, but just opentelemetry.trace.Span sounds more casual that openelemetry.api.trace.Span.

That's true.

[jkwatson]

@carlosalberto and @bogdandrutu any opinions on this?

[tylerbenson]

I'm in favor of putting the api under io.opentelemetry.api.

[iNikem]

One more argument in favor: JPMS.

[jkwatson]

One more argument in favor: JPMS.

To follow-up from this comment. It appears that you can't have 2 JPMS modules that export the same package consumed by a single application. (I haven't been able to find actual documentation of this yet, but many examples of people complaining about it). So, if have java 9 modules for our libraries, we would definitely not want to have 2 modules exporting io.opentelemetry as a public package, otherwise you couldn't use both the API and the SDK in the same application. Which, of course, would kind of defeat the purpose.

So, 👍 on this change, given that we could potentially be breaking users who are using the JPMS module system if we don't change the packaging strategy.

[jkwatson]

Note: I did find this in the JVM JLS diffs for JPMS (https://cr.openjdk.java.net/~mr/jigsaw/spec/java-se-9-jvms-diffs.pdf)

A class created by a class loader is in exactly one run-time package and therefore
exactly one run-time module, because the Java Virtual Machine does not support
a run-time package being associated with (or more evocatively, "split across")
multiple run-time modules