"Alpha" status of the libraries provided by the opentelemetry-java-contrib project

[cyrille-leclerc]

Dear all,

Did we discuss the "alpha" status of the libraries provided by the opentelemetry-java-contrib project?

I feel the OpenTelemetry Maven Extension is in a more mature stage than "alpha" and I guess it's similar for the JMX Metrics component. I don't know for the other components as I didn't have the time to use them.

[trask]

hey @cyrille-leclerc!

Thanks for bringing this up.

We discussed in SIG meetings today, and I wrote up a potential proposal that came out of those discussions: open-telemetry/opentelemetry-java-instrumentation#5617

This would potentially allow us to bump the maven extension to "beta" once we are ready to commit to API stability. Let us know when you are ready for this and we will help do a thorough review of public API surface, and we will port the automation over to this repo from the opentelemetry-java repo that helps track / ensure that there are no breaking API changes going forwards.

To get to "stable" (telemetry stability), I think we would want to have stable semantic conventions around build tools in general. I don't think maven-specific semantic conventions have to be in the specification repository, since there's probably just one implementation of them, so we could publish a schema file / schema url from this repository (the schema file / schema url allows for some schema evolution, e.g. renaming of attributes, without those being breaking, because there will be tooling in the collector that can automatically map them based on the schema files, see open-telemetry/opentelemetry-specification#2180 details, but we can definitely help you through this process once we get there).

[cyrille-leclerc]

Thanks @trask for taking the time to answer.

I see different dimensions to what is the stability of Otel Maven Extension and probably more generally to the stability of instrumentations:

• Stability of the source code APIs
  • Stability of "officially supported" extension mechanisms to add more coverage to the instrumentation.
    • It would be the MojoGoalExecutionHandler for the Otel Maven Extension if we wanted to officially support such an extension mechanism. which is not the case yet.
  • I see a difference between "code with public visibility" and what is "officially supported" in a language like Java because
    • We need public visibility of some pieces of code to get visibility across java packages while maybe not wanting to "officially support" this public code
    • We don't want to go through the rigidity of a packaging system like OSGi so we won't be able to technically prevent the visibility of some that we don't want to officially support but that is marked as public.
  • More generally, the OTel Maven Extension is not willing to officially support any source code API as we see the Otel MAven Extension as a self sufficient component for the moment
• Stability of the configuration
  • Commit to backward compatibility of the configuration parameters
• Stability of the produced Otel traces, metrics, and logs
  • I see the value of some of this stability for users to define automated processes (primarily the stability of attributes and metrics) but at the same time, I'm afraid that the commitment of backward compatibility on details like log messages or details of traces may be too big of an effort and block innovation.

With all this said:

• This exercise above makes me think that the Otel Maven Extension is NOT ready for "stability"
• And I also feel the "alpha" status is not reflecting the production readiness of the component and this challenge is bigger that the Otel Maven Extension, it impacts all the Otel Components that still have the "alpha" label.

I don't see a simple solution for the moment to this challenge so I'm inclined to icebox the question for the moment and bring it back if we see clear problems with adoption due to this "alpha" qualifier.

Does it make sense @trask ?

[trask]

I see a difference between "code with public visibility" and what is "officially supported" in a language like Java

the solution we have adopted is to throw these classes under a package named internal, e.g. io.opentelemetry.api.internal.Utils and flag them with a class-level javadoc stating This class is internal and is hence not for public use. Its APIs are unstable and can change at any time.

the OTel Maven Extension is not willing to officially support any source code API as we see the Otel Maven Extension as a self sufficient component for the moment

this is great, let's rename io.opentelemetry.maven.* to io.opentelemetry.maven.internal.* to signify this and then the component will be "API-stable" 😄

do you think labeling the maven extension as beta would help at all (open-telemetry/opentelemetry-java-instrumentation#5617)?

totally agree with, and thanks for voicing your other points, we are working through similar concerns across the instrumentation repo