JmFrX - A bridge for capturing JMX data with JDK Flight Recorder

The JmFrX project allows to periodically capture JMX MBeans and emit a corresponding JDK Flight Recorder (JFR) event. This allows to

• Track changes to the values of JMX MBean attributes over time without resorting to external monitoring tools
• Access JMX data from offline JFR recording files in situations where you cannot directly connect to JMX
• Emit JMX data via the JFR event streaming API (JEP 349)

More details about JmFrX, its motivation and implementation can be found in the official project announcement. To learn more about JFR itself, please refer to this blog post.

Usage

This project requires OpenJDK 11 or later at runtime.

JmFrX is not yet available from Maven Central yet; in the meantime you can obtain snapshot builds from JitPack. To so, add the following dependency to your project's pom.xml:

...
<dependency>
  <groupId>com.github.gunnarmorling</groupId>
  <artifactId>jmfrx</artifactId>
  <version>master-SNAPSHOT</version>
</dependency>
...

Alternatively, build JmFrX from source (see below) yourself and add the following dependency to your project's pom.xml:

...
<dependency>
  <groupId>dev.morling.jmfrx</groupId>
  <artifactId>jmfrx</artifactId>
  <version>1.0-SNAPSHOT</version>
</dependency>
...

Then, register the JmFrX event type with Flight Recorder in the start-up routine of your program, e.g. its main method, the static initializer of a class loaded early on, an eagerly initialized Spring or CDI bean, etc. A Java agent for this purpose will be provided as part of this project soon. When using Quarkus, an application start-up event listener can be used like so:

@ApplicationScoped
public class EventRegisterer {

  public void registerEvent(@Observes StartupEvent se) {
    Jmfrx.getInstance().register();
  }

  public void unregisterEvent(@Observes ShutdownEvent se) {
    Jmfrx.getInstance().unregister();
  }
}

Start your application.

Now create a JFR configuration file, enabling the JmFrX event type. To do so, open JDK Mission Control, and choose your application in the JVM Browser. Then follow these steps:

• Right-click the JVM -> Flight Recorder -> Start Flight Recording...
• Click on Template Manager
• Copy the Continuous setting and Edit this copy
• Expand the JMX and JMX Dump nodes
• Make sure the event is Enabled, choose a period for dumping the chose JMX MBeans (defaults to 60 s) and select the MBeans to be dumped by means of a regular expression, which matches one or more JMX object names:

• Click OK and OK
• Make sure that the template you edited is selected under Event settings
• Click Finish to begin the recording

Once the recording is complete, open the recording file in JDK Mission Control and go to the Event Browser. You should see periodic events corresponding to the selected MBeans under the JMX node:

When not using JDK Mission Control to initiate recordings, but the jcmd utility, also create a configuration as described above. Then export the file from the template manager and specify its name to jcmd via the settings=/path/to/settings.jfc parameter.

Build

This project requires OpenJDK 14 or later for its build. Apache Maven is used for the build. Run the following to build the project:

mvn clean install

Related Work

JDK Mission Control project lead Marcus Hirt discussed a similar project in a blog post in 2016. But unlike the implementation described by Marcus in this post, JmFrX is based on the public and supported APIs for defining, configuring and emitting JFR events, as available since OpenJDK 11.

License

This code base is available ander the Apache License, version 2.