Add ability to drop JMX MBean attributes and aggregate properly

[SylvainJuge]

With JMX Insights, we have the ability to capture JMX metrics using a simple YAML configuration file.

As found while working on #14067 , some JMX MBeans have some technical details leak into their object names, which forces to capture extra "technical metric attributes" that are not relevant for the metric consumer.

MBeans are published in a tree-like structure with optional key/value pairs, the metric values are extracted from their MBean attributes.

JMX metrics are extracted from those using one or more MBean query that can have wildcards for those key/value pairs

For example, with the Jetty application server, when we need to capture the "select count" metric:

• org.eclipse.jetty.io:context=*,type=managedselector,id=* MBean query allows to get all the MBean instances providing the selectCount MBean attribute
• by default 10 instances of such MBean exist, each with a distinct value of id key.
• the current JMX implementation will attempt to capture all of those as 10 distinct metrics with the same identity unless we map the id key value as a metric attribute, hence producing 10 distinct metrics.
• we need to provide the aggregate sum of selectCount attribute over all those instances and capture it as a single metric
• in this particular case, in addition the context key also needs to be discarded because there is often a single transient value (thus potentially high-cardinality over time).

Here is how it looks like with VisualVM:

The context key value is equal to HTTP_1_1@524d6d96, and the id key have 10 distinct values from 0 to 9.

Having the ability to discard some metrics attributes and perform relevant aggregation seems to be possible through the usage of metric views, so I think we should be able to leverage this feature and apply it for JMX metrics.

For the distinct values of id having those as metric attributes is not relevant for the metric consumer.

For the context key, we can consider this as an exception (but one we have to get by) as it goes against the recommendations for MBean names, in particular for this statement:

The name of the same object should not change between different executions of the application, so for example it should not contain items like a "JVM id" or the "MBean Server Id" that will change with each execution

[trask]

hi @SylvainJuge! we discussed this in Java SIG.

I think InstrumentBuilder#setAdviceAttributes will work for this.

e.g. for

opentelemetry-java-instrumentation/instrumentation/jmx-metrics/javaagent/src/main/resources/jmx/rules/jetty.yaml

Lines 3 to 22 in c904a8f

	- bean: org.eclipse.jetty.server.session:context=*,type=sessionhandler,id=*
	unit: s
	prefix: jetty.session.
	type: updowncounter
	metricAttribute:
	resource: param(context)
	mapping:
	sessionsCreated:
	unit: "{sessions}"
	type: counter
	desc: The number of sessions established in total
	sessionTimeTotal:
	type: counter
	desc: The total time sessions have been active
	sessionTimeMax:
	type: gauge
	desc: The maximum amount of time a session has been active
	sessionTimeMean:
	type: gauge
	desc: The mean time sessions remain active

you would call setAdviceAttributes with the 4 attributes you want on the metrics (sessionsCreated, sessionTimeTotal, sessionTimeMax, sessionTimeMean)

then when recording the metric values, you would pass in all 6 attributes (the 4 above + context and id)

then the SDK internally will drop the 2 that aren't in the "advice attributes" and aggregate over those dimensions

this is the same way we are handling HTTP metrics in the Java agent (recording all span attributes, but limiting which attributes make it onto the metric via advice attributes).

oh, InstrumentBuilder#setAdviceAttributes is package protected but there's a public incubator api that you can use instead

[SylvainJuge]

After further investigation the current implementation works as expected, so there is nothing to change in the implementation. It does however produce unpredictable results with gauge metrics when more than one MBean instance is queried due to the last-value aggregation.

As a consequence I have opened #14111 to properly test and document this behavior.

Regarding the Jetty PR #14067 it means that we should probably avoid gauge metrics as we can't assume only a single MBean instance would be present.

[SylvainJuge]

As discussed during the 2025-06-26 Java SIG meeting, it's probably better for now to void gauge metrics with aggregation over multiple MBeans, if needed we can re-evaluate this in the future.

This also mean avoiding such metrics in the embedded metrics definitions of instrumentation, however it would always be possible to define them through custom metrics YAML.

As a consequence, #14067 will be reworked to remove such metrics.