jmx metrics provide registry + weaver validation

[SylvainJuge]

As described in the discussion of #16016

• instrumentation should only produce stable metrics by default, users should be able to opt-in for other metrics.
• JMX metrics are not formally defined nor have stability definition
• some of the target systems do have experimental- prefix to indicate their definitions are not stable
  • this creates breaking changes for users when metrics are promoted
  • this prevent promoting metrics one by one, it's all or nothing
• users have to know the relevant values to use for otel.jmx.target.system in order to get the metrics, whereas the presence of MBeans should be enough to know if a given system needs to be monitored.

In order to solve this, we need to have the following:

• a formal definition of JMX metrics that is consistent with upstream semantic conventions, it should be compatible with the "federated semconv" to be reusable/imported by end users
• having the ability to select JMX metrics on their stability level, rather than having to enumerate the "target system", in other words: "capture what is available in the JMX tree for a given maturity level".
  • doing this automatic discovery is not strictly required here but allows to remove the need to define and maintain the values for otel.jmx.target.system.

Once this is complete we should have:

• otel.jmx.target.system configuration option is optional or deprecated
• added the ability to select JMX metrics on their stability level, the default should be stable.
• a folder in this repository that contains reusable definitions of existing JMX metrics and can be used with a "federated semconv" strategy
• the ability to start formally promoting some of those JMX metrics as stable.

Relates to

• [jmx-scraper] Create correctness tests against target systems opentelemetry-java-contrib#2073
• [jmx-scraper] Create weaver model for jmx-scraper metrics opentelemetry-java-contrib#2072
• [jmx-scraper] Create weaver model for metrics of "activemq" target system opentelemetry-java-contrib#2349

Implementation steps

• start registry + validate with integration tests
  • [jmx-metrics] bootstrap + validate registry definitions for jmx metrics #19139
  • tomcat
  • jvm (inherited from semconv)
• add definition and validation with other supported systems
  • activemq
    • add jmx weaver validation to activemq #19247
    • fixes [jmx-scraper] Create weaver model for metrics of "activemq" target system opentelemetry-java-contrib#2349
  • camel add weaver validation to camel jmx metrics #19248
  • wildfly jmx weaver validation for wildfly #19246
  • jetty add weaver validation to jetty jmx metrics #19249
  • kafka-broker
  • kafka-connect
  • hadoop
  • cassandra
• add the ability to auto-discover all available metrics
  • jmx-metrics add ability to filter/include metrics by target system and metric maturity #19245
• add the ability to filter (or opt-in) metrics on maturity level
  • jmx-metrics add ability to filter/include metrics by target system and metric maturity #19245
• test: find a way to make weaver enforce metrics descriptions/brief for consistency
• test: find a way to ensure jmx metrics stability is in sync with JMX metrics registry

Follow-up step(s)

• optional: promotion of JMX metrics to stable
• required: ensure feature parity in jmx-scraper

Optional but related step(s)

• optional: automate generation of JMX metrics documentation from registry
• optional: reduce duplication between JMX metrics tests and weaver validation (instrument type, unit, metric description), some aspects are not covered by weaver like assert on numeric value or attribute value.
• optional: reduce duplication in metrics definition yaml, either through weaver generation (with annotations), or by providing a way to link to JMX metrics registry definitions.
  • the opposite approach (jmx yaml to registry yaml) was suggested in jmx metrics generate weaver yaml from jmx metrics yaml #15196, but this prevents reusing the registry as-is.