Why some classes in io.opentelemetry.instrumentation.jmx.engine are not public?

[mfridljand]

In the io.opentelemetry.instrumentation.jmx.engine in the library some classes are declared as public, but some not. Why?
Examples of public classes are

MetricAttributeExtractor
MetricDef
MetricConfiguration

Examples of classes with package access are

MetricRegistrar
BeanFinder

I am trying to enhance the current implementation by a custom MetricAttributeExtractor. In my environment there are security issues for some MBeans. For example, there are following exceptions in the agent's log file

[otel.javaagent 2025-11-27 15:12:43:513 +0100] [jmx_bean_finder] DEBUG io.opentelemetry.javaagent.shaded.instrumentation.jmx.engine.BeanAttributeExtractor - Resolving MemoryUsed for java.nio:type=BufferPool,name=mapped
[otel.javaagent 2025-11-27 15:12:43:513 +0100] [jmx_bean_finder] DEBUG io.opentelemetry.javaagent.shaded.instrumentation.jmx.engine.BeanAttributeExtractor - Exception com.sap.engine.services.jmx.exception.JmxSecurityException: Caller Guest not authorized, required permission missing ("javax.management.MBeanPermission" "-#-[java.nio:name=mapped,type=BufferPool]" "getMBeanInfo")  while inspecting attributes for ObjectName java.nio:type=BufferPool,name=mapped

This is a kind of known issue which may be fixed in an extension. Ideally, the JMX rules .yaml would support extending by a “declarative instantiation”: that is, have an additional property to specify a MetricAttributeExtractor implementation from an extension. E.g.

- bean: java.lang:type=MemoryPool,name=*
  exporter: io.opentelemetry.instrumentation.jmx.engine.MetricAttributeExtractor
  prefix: jvm.memory.
  type: updowncounter
  unit: By
  ...

If it can work that way, of course))

It seems it can only be changed right now by copy&paste of JmxMetricInsight and JmxMetricInsightInstaller etc. It would be nice when other classes were public.

Thanks!

[trask]

cc @SylvainJuge @robsunday @PeterF778

[PeterF778]

Some classes of JMX Insight are not public, just because public access was not needed. If I understand your intentions correctly, you'd like to create subclasses for MetricAttributeExtractor. Is this to be used by your agent extension only, or would you like it to be part of a repo?

[SylvainJuge]

Access to internal classes will soon be removed with changes related to #14674, so this is definitely not something I would suggest to rely on.

Could you describe how would your own implementation of MetricAttributeExtractor would differ from the current implementation ? For example:

• handle a specific exception, for example to provide a human-friendly error message
• wrap the call to the MBean with extra code that handles the security (For example with SecurityManager we have to wrap calls with AccessController.doPrivileged(java.security.PrivilegedAction<T>))

Providing the ability to extend how MBeans are accessed could be done with:

• providing a public SPI interface to allow users to provide their own implementation
• the implementation would likely be provided through a custom extension, which could then be loaded by JmxMetricInsightInstaller at runtime to provide auto-configuration.

[mfridljand]

Well, perhaps I asked the question a bit too early—I don’t yet have an implementation for the Otel Java agent.

JMX works fine in general. From the agent’s log, the issue occurs for
java.nio:type=BufferPool,*
but does not occur, for example, for
java.lang:type=MemoryPool,*

This error is known to appear with some other APMs when querying proprietary application server MBeans. However, it has not been observed for standard JVM MBeans from java.lang.management.* that are used for basic JVM metrics such as memory or CPU utilization.
In short, the error was previously fixed in an agent extension consisting of two main components: an advice-like “hook” and a JMX poller. The extension's "hook" (or “advice” in Otel terminology) matches a privileged application that has the necessary permissions. When executed, it uses the application’s AccessController and ClassLoader to dynamically instantiate the JMX poller service, thereby inheriting the application’s permissions.

So, MetricAttributeExtractor is probably not enough.

[SylvainJuge]

I see, so in order to invoke some of those MBeans on this application you need to use application-provided AccessController and be able to get access to application classes, for example to access application-specific exception types.

Outside of the permission problem, are there any application-specific classes really needed ? In other words, if we leave the permissions aside does those MBeans work like other JVM MBeans and we can use the usual JMX API to query them ?

What I find a bit surprising here that those MBeans like java.nio:type=BufferPool,* are not specific to any application server, they are just standard JVM MBeans provided by default, so it is possible there is a "generic permission check" added to the JVM. I'm not aware of such feature in JMX, but maybe if you share a bit more details, for example with a stacktrace it could help identify what is causing this (and then maybe find a way to work-around this).

The good news here is that you may already have an existing solution for this, so at least you know have one possible implementation for it, just not how to do it with OpenTelemetry instrumentation.

In order to investigate this further it could help to provide the following:

• a bit more details on the application server, is that something already supported outside of JMX ?
• a stack trace of the exception (feel free to redact some parts if you'd like)
• the JVM system properties, it may contain an explicit setting to setup the "permission check" in JMX if such thing exist (feel free to redact as well here).

If the problem here is just a "permission check" and no specific class is needed to query the MBeans, I think the simplest solution would be to instrument the part that does the permission checks to allow querying metrics.

[SylvainJuge]

Well, after a bit of research there appears to not have any visible JVM system property to control that, however in the JMX API we have javax.management.remote.JMXConnectorServer where the setMBeanServerForwarder(javax.management.remote.MBeanServerForwarder) method allows to setup a way to wrap all the client calls, so we can assume something similar is used in this case.

If that's the case, then it should be possible to create an instrumentation extension that would instrument the MBeanServerForwarder instance used and allow the calls from JMX metrics polling, the only tricky part would be to only selectively enable it when called from JMX metrics polling. Maybe it could be simpler to just enable reading all MBean attributes when called from within the JVM, I think we could assume there should be very little risk to see any sensitive information exposed in JMX.