feat: instrumentation description in base class constructor

[blumamir]

This PR adds a new type for InstrumentationMetadata which currently holds description.

The description field is currently part of the Instrumentation interface here:

  /**
   * Instrumentation Description - please describe all useful information
   * as Instrumentation might patch different version of different modules,
   * or support different browsers etc.
   */
  instrumentationDescription?: string;

But it was not an argument the the base class constructor, thus not being utilized by any core or contrib instrumentation packages.

This PR replaces the instrumentationDescription with a more general object for metadata which at the moment only contains description but it might hold additional info soon.

It allows existing instrumentations to register the description, making it useable for tolling and distributions to consume.

To make the process automatic, I assume the description in the package.json is the instrumentation description, save it into version.ts with the version-update.js script, and then use it in each instrumentation separately. This gives us cleaner code (no magic long strings), consistency with the text in package.json, and less manual work.

The work on making sure all descriptions are meaningful and consistent is done as #4715 and open-telemetry/opentelemetry-js-contrib#2202. Adding the new argument to the constructor is made after #4695
is merged which also made a fix to the constructor arguments.

The PR is not breaking, besides removing the instrumentationDescription property from Instrumentation interface which was not used anywhere and never referenced in core or contrib, but still part of the public api

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.30%. Comparing base (2610122) to head (a91f419).
Report is 35 commits behind head on main.

❗ Current head a91f419 differs from pull request most recent head 473e032

Please upload reports for the commit 473e032 to get more accurate results.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4716      +/-   ##
==========================================
+ Coverage   90.77%   92.30%   +1.53%     
==========================================
  Files          90      178      +88     
  Lines        1930     4563    +2633     
  Branches      417     1012     +595     
==========================================
+ Hits         1752     4212    +2460     
- Misses        178      351     +173     

Files	Coverage Δ
...emetry-instrumentation-grpc/src/instrumentation.ts	96.25% <100.00%> (ø)
...ges/opentelemetry-instrumentation-http/src/http.ts	92.94% <100.00%> (ø)

... and 137 files with indirect coverage changes

[blumamir]

@david-luna this PR is a followup to our discussion in #4695

Please feel free to leave any comments or concerns on this proposed change.

[blumamir]

Since this data is stataic per instrumentation, other alternatives to passing this info via the constructor are:

override public function

similar to how InstrumentationModuleDefinition[] are returned from init(), we can add a function like public metadata(): InstrumentationMetadata to returned this info when needed:

  metadata(): InstrumentationMetadata {
    return {
      description: PACKAGE_DESCRIPTION,
    }
  }

set public optional property

we can make this property nullable in Instrumentation interface like so:

export interface Instrumentation {
// ...
  instrumentationMetadata?: InstrumentationMetadata;

and then have each instrumentation optionally defining this property, something like:

export class HttpInstrumentation extends InstrumentationBase<HttpInstrumentationConfig> {

  public InstrumentationMetadata: InstrumentationMetadata = {
    description: PACKAGE_DESCRIPTION,
  }

[pichlermarc]

I'd still mark this as breaking.
While we don't use this in contrib users may set it in their custom instrumentation packages and that'd be breaking for them.

[pichlermarc]

I wonder if this makes sense for instrumentations that target the browser. It adds to the bundle size. We can also not tree-shake it out even though it's never really used.

[blumamir]

That's a good point. We can choose to omit it for browser instrumentations, or come up with different way to expose this information that is easily integrated into tools and distributions.

I will open a separate issue to discuss my future plans on adding more metadata, and bring it up in the SIG.

Thank you for the feedback and for raising these concerns.

[blumamir]

as a reference, collector repo define metadata.yaml files per component which include stuff like this:

type: otlp

status:
  class: exporter
  stability:
    stable: [traces, metrics]
    beta: [logs]
  distributions: [core, contrib]

[blumamir]

#4725