To configure event settings, use setSettings(Map).

To configure event settings, use setSettings(Map).

The following example connects to a remote host and stream events using settings from the "default" configuration.

 {
     

     String host = "com.example";
     int port = 4711;

     String url = "service:jmx:rmi:///jndi/rmi://" + host + ":" + port + "/jmxrmi";

     JMXServiceURL u = new JMXServiceURL(url);
     JMXConnector c = JMXConnectorFactory.connect(u);
     MBeanServerConnection conn = c.getMBeanServerConnection();

     try (final var rs = new RemoteRecordingStream(conn)) {
         rs.onMetadata(e -> {
             for (Configuration c : e.getConfigurations()) {
                 if (c.getName().equals("default")) {
                     rs.setSettings(c.getSettings());
                 }
             }
         });
         rs.onEvent(System.out::println);
         rs.start();
     }

 
 

If multiple events with same name (for example, the same class is loaded in different class loaders), then all events that match the name are disabled.

If multiple events have the same name (for example, the same class is loaded in different class loaders), then all events that match the name are enabled.

To control the amount of recording data stored on disk, the maximum length of time to retain the data can be specified. Data stored on disk that is older than the specified length of time is removed by the Java Virtual Machine (JVM).

If neither maximum limit or the maximum age is set, the size of the recording may grow indefinitely if events are not consumed.

To control the amount of recording data that is stored on disk, the maximum amount of data to retain can be specified. When the maximum limit is exceeded, the Java Virtual Machine (JVM) removes the oldest chunk to make room for a more recent chunk.

If neither maximum limit or the maximum age is set, the size of the recording may grow indefinitely if events are not consumed.

The size is measured in bytes.

To perform an action on a subset of event types, consider using EventStream.onEvent(String, Consumer) and EventStream.onMetadata(Consumer) as it is likely more performant than any selection or filtering mechanism implemented in a generic action.

If an action is not registered, an exception stack trace is printed to standard error.

Registering an action overrides the default behavior. If multiple actions have been registered, they are performed in the order of registration.

If this method itself throws an exception, resulting behavior is undefined.

If the stream is already closed, the action will be performed immediately in the current thread.

If a stream is started, asynchronously or synchronously, it is stopped immediately or after the next flush. This method does NOT guarantee that all registered actions are completed before return.

Closing a previously closed stream has no effect.

If the action has been registered multiple times, all instances are unregistered.

If reuse is set to true, an action should not keep a reference to the event object after the action has completed.

The start time must be set before starting the stream

The end time must be set before starting the stream.

At end time, the stream is closed.

Actions are performed in the current thread.

To stop the stream, use the EventStream.close() method.

Actions are performed in a single separate thread.

To stop the stream, use the EventStream.close() method.

Stops a started stream and waits until all events in the recording have been consumed.

Invoking this method in an action, for example in the onEvent(Consumer) method, could block the stream indefinitely. To stop the stream abruptly, use the close() method.

The following code snippet illustrates how this method can be used in conjunction with the startAsync() method to monitor what happens during a test method:

Copy

  AtomicLong bytesWritten = new AtomicLong();
  try (var r = new RemoteRecordingStream(connection)) {
    r.setMaxSize(Long.MAX_VALUE);
    r.enable("jdk.FileWrite").withoutThreshold();
    r.onEvent(event ->
      bytesWritten.addAndGet(event.getLong("bytesWritten"))
    );
    r.startAsync();
    testFoo();
    r.stop();
    if (bytesWritten.get() > 1_000_000L) {
      r.dump(Path.of("file-write-events.jfr"));
      throw new AssertionError("testFoo() writes too much data to disk");
    }
  }

The recording stream must be started, but not closed.

It's highly recommended that a max age or max size is set before starting the stream. Otherwise, the dump may not contain any events.