[instrumentation] instrumentation base stabilization plan

[pichlermarc]

Description

The @opentelemetry/instrumenation package is the base package used for all instrumentations. To reduce the maintenance burden for instrumentation authors which currently need to deal with possible breaking changes as well as users that use the instrumentation registration mechanism, we should promote the @opentelemetry/instrumenation package to stable.

Currently the following issues prevent stabilization:

Logs API stabilization:

Types from the logs API are used in the public interface and may break type compatibility when using different versions of the instrumentation base in the same app. Therefore we need to hold off on marking the @opentelemetry/instrumentation package as stable until the Logs API is integrated into the @opentelemetry/api package as a stable component.

This will be addressed by

• Integrate @opentelemetry/api-logs package into @opentelemetry/api #4400
• TBD(if API was moved to @opentelemetry/api/experimental in Integrate @opentelemetry/api-logs package into @opentelemetry/api #4400, issues to stabilize the API)

Public API surface review:

We should replace any occurrence of export * with explicit exports and and review the API surface for any types and functions that we may be able to remove.

This will be addressed by

• (TBD) issue to review the API surface
• (TBD) depending on review of the API surface, a follow-up to deal with types and functions that we decided to remove

ESM instrumentation:

We currently offer an instrumentation customization hook for ESM in Node.js which uses import-in-the-middle. As of writing, the customization hooks concept is not yet stable in Node.js, but it is already available as a RC.

We should therefore explicitly document one or multiple minimum supported Node.js versions / version ranges (especially with regards to Node.js LTS versions) based on the stability of the customization hook in that Node.js version. If no versions are stable yet declare the provided customization hook as fully experimental. Update versions as needed.

We should also document that direct usage of import-in-the-middle/hook.mjs may cease to work in the future and is purely experimental to prevent being locked into using import-in-the-middle until the next major version, should we decide to move on from using that package for ESM instrumentation in the future and implement our own version of the customization hook at @opentelemetry/instrumentation/hook.mjs

We should also update documentation on how to set this customization hook when using the Node.js binary, be it via --import or otherwise, and explicitly declare all other ways that may be introduced in future Node.js versions as not directly supported (we may declare them as supported in a new minor version).

This will be addressed by

• (TBD) issue to document Node.js versions supported by the customization hook, or none if the concept is not stable yet
• (TBD) issue to document that direct usage of import-in-the-middle/hook.mjs is unsupported
• (TBD) issue to update documentation on supported ways how to set the customization hook