[instrumentation] research adding experimental features to Instrumentation, InstrumentationBase

[pichlermarc]

Description:

Types from @opentelemetry/api-logs are used in the public interface and may break compatibility when using different versions of the instrumentation base in the same app. It also may break (type-)compatibility if there's a different version of @opentelemetry/api-logs installed in the end-user's app and the @opentelemetry/instrumentation package. These breakages can occur even if the user does not use these experimental features.

Once we release @opentelemetry/instrumentation as 1.x, the public interface should only include types from stable packages. As such we may need to remove @opentelemetry/api-logs types from the public interface before we stabilize @opentelemetry/instrumentation. Further, we may want to add experimental functionality to the @opentelemetry/instrumentation package (for instance @opentelemetry/api-events). Before releasing the package as stable, we want to ensure that we add new experimental and stable features in a non-breaking manner.

This issue is intended to track research on this topic and should lead to an issue to find and prototype a solution to this problem.
Keep in mind that the current structure of @opentelemetry/instrumentation may not be well-suited to adding features like this and may require significant changes.

This issue is considered done when:

• An approach has been found and presented to the SIG (in the SIG meeting or in a seperate meeting set up by the @open-telemetry/javascript-maintainers)
  • This should include a draft PR in advance which illustrates the chosen approach, including any neccessary changes to at least one instrumentation package here in this repo. (examples: @opentelemetry/instrumentation-http, @opentelemetry/instrumentation-grpc)
• The approach was accepted by the maintainers (indicated when maintainers reach consensus on the draft PR)
• A follow-up issue was crated and linked here as well as in [instrumentation] instrumentation base stabilization plan #4586 and in the contrib repo to implement the chosen approach.

Approaches to consider:

This section lists possible approaches to consider. The list of approaches here is intended to get the person working on this started. If you find better options, feel free to prototype and pursue these options.

experimental entrypoint:

Creating an @opentelemetry/instrumentation/experimental entrypoint with ExperimentalInstrumentation and ExperimentalInstrumentationAbstract exports that extend Instrumentation and InstrumentationAbstract can be an option. Experimental features may be added to these interfaces, and consumers of this entrypoint MUST depend on a tilde version (~1.2.3) of the stable @opentelemetry/instrumentation if they consume experimental features.

Doing so may allow instrumentation that do not provide experimental signals to depend on ^1.0.0 of @opentelemetry/instrumentation.

Reconsider extending InstrumentationAbstract in every instrumentation

We may need to consider moving away from the current model where instrumentations extend InstrumentationAbstract as adding any non-optional field (even protected and private can be breaking for TypeScript users).

One option may be changing the Instrumentation interface to allow passing an InstrumentationHelper that provides the current functionality of InstrumentationAbstract. Instrumentations may then implement the Instrumentation interface directly. This approach here would likely also require us to have a way to pass an ExperimentalInstrumentationHelper to the the Instrumentation, which may also require an experimental entrypoint or at least @experimental annotations, similar to what is mentioned in the previous section.

Side note: when going this was we may go with a soft approach of launching 1.x with a deprecated InstrumentationAbstract still available to avoid current implementations from breaking, but strongly recommend people move to the new approach

Additional Notes:

• While not explicitly mentioned in the specification, we consider Instrumentation to be a "plugin interface" as described by the spec and types exported by @opentelemetry/instrumentation should adhere to this spec
  • https://github.com/open-telemetry/opentelemetry-specification/blob/3266af01f50e1cd77c25b5c32c3b499c0161d910/specification/upgrading.md?plain=1#L117-L122

This issue is part of #4586