Creates an event stream for the current JVM (Java Virtual Machine).

Exceptions

IllegalStateException:

if Flight Recorder can't be created (for example, if the Java Virtual Machine (JVM) lacks Flight Recorder support, or if the file repository can't be created or accessed)

Creates a recording stream using settings from a configuration.

The following example shows how to create a recording stream that uses a predefined configuration.

var c = Configuration.getConfiguration("default");
try (var rs = new RecordingStream(c)) {
    rs.onEvent(System.out::println);
    rs.start();
}

Parameters

configuration:Configuration

configuration that contains the settings to use, not null

Exceptions

IllegalStateException:

if Flight Recorder can't be created (for example, if the Java Virtual Machine (JVM) lacks Flight Recorder support, or if the file repository can't be created or accessed)

See Also

Configuration

Implements jdk.jfr.consumer.EventStream.awaitTermination.

Doc from jdk.jfr.consumer.EventStream.awaitTermination.

Blocks until all actions are completed, or the stream is closed, or the timeout occurs, or the current thread is interrupted, whichever happens first.

Annotations

@Override

Exceptions

InterruptedException:

if interrupted while waiting

Implements jdk.jfr.consumer.EventStream.awaitTermination.

Doc from jdk.jfr.consumer.EventStream.awaitTermination.

Blocks until all actions are completed, or the stream is closed, or the current thread is interrupted, whichever happens first.

Annotations

@Override

Exceptions

InterruptedException:

if interrupted while waiting

Implements java.lang.AutoCloseable.close, jdk.jfr.consumer.EventStream.close.

Doc from java.lang.AutoCloseable.close.

Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by the try-with-resources statement.

Annotations

@Override

Disables event with the specified name.

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. To disable a specific class, use the disable(Class) method or a String representation of the event type ID.

Parameters

name:String

the settings for the event, not null

Returns:EventSettings

an event setting for further configuration, not null

Disables event.

Parameters

eventClass:Class<? extends Event>

the event to enable, not null

Returns:EventSettings

an event setting for further configuration, not null

Exceptions

IllegalArgumentException:

if eventClass is an abstract class or not a subclass of Event

Writes recording data to a file.

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.

Parameters

destination:Path

the location where recording data is written, not null

Exceptions

IOException:

if the recording data can't be copied to the specified location, or if the stream is closed, or not started.

Since

17

See Also

RecordingStream#setMaxAge(Duration), RecordingStream#setMaxSize(long)

Enables the event with the specified name.

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 enable a specific class, use the enable(Class) method or a String representation of the event type ID.

Parameters

name:String

the settings for the event, not null

Returns:EventSettings

an event setting for further configuration, not null

See Also

EventType

Enables event.

Parameters

eventClass:Class<? extends Event>

the event to enable, not null

Returns:EventSettings

an event setting for further configuration, not null

Exceptions

IllegalArgumentException:

if eventClass is an abstract class or not a subclass of Event

Implements jdk.jfr.consumer.EventStream.onClose.

Doc from jdk.jfr.consumer.EventStream.onClose.

Registers an action to perform when the stream is closed.

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

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.onError.

Doc from jdk.jfr.consumer.EventStream.onError.

Registers an action to perform if an exception occurs.

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.

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.onEvent.

Doc from jdk.jfr.consumer.EventStream.onEvent.

Registers an action to perform on all events matching a name.

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.onEvent.

Doc from jdk.jfr.consumer.EventStream.onEvent.

Registers an action to perform on all events in the stream.

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

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.onFlush.

Doc from jdk.jfr.consumer.EventStream.onFlush.

Registers an action to perform after the stream has been flushed.

Annotations

@Override

Overrides default jdk.jfr.consumer.EventStream.onMetadata.

Registers an action to perform when new metadata arrives in the stream. The event type of an event always arrives sometime before the actual event. The action must be registered before the stream is started.

The following example shows how to listen to new event types, register an action if the event type name matches a regular expression and increase a counter if a matching event is found. A benefit of using an action per event type, instead of the generic onEvent(Consumer) method, is that a stream implementation can avoid reading events that are of no interest.

static long count = 0;
public static void main(String... args) throws Exception {
    String regExp = args[0];
    var pr = Pattern.compile(regExp).asMatchPredicate();
    Configuration c = Configuration.getConfiguration("default");
    try (var s = new RecordingStream(c)) {
        s.setOrdered(false);
        s.onMetadata(metadata -> metadata.getAddedEventTypes()
         .stream().map(EventType::getName).filter(pr)
         .forEach(eventName -> s.onEvent(eventName, event -> count++)));
        s.startAsync();
        System.out.println("Running recording for 5 s. Please wait.");
        s.awaitTermination(Duration.ofSeconds(5));
        System.out.println(count + " events matches " + regExp);
    }
}

Parameters

action:Consumer<MetadataEvent>

to perform, not null

Annotations

@Override

Exceptions

IllegalStateException:

if an action is added after the stream has started

Since

16

Implements jdk.jfr.consumer.EventStream.remove.

Doc from jdk.jfr.consumer.EventStream.remove.

Unregisters an action.

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

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.setEndTime.

Doc from jdk.jfr.consumer.EventStream.setEndTime.

Specifies the end time of the stream.

The end time must be set before starting the stream.

At end time, the stream is closed.

Annotations

@Override

Determines how far back data is kept for the stream.

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 the maximum limit nor the maximum age is set, the size of the recording may grow indefinitely if events are not consumed.

Parameters

maxAge:Duration

the length of time that data is kept, or null if infinite

Exceptions

IllegalArgumentException:

if maxAge is negative

IllegalStateException:

if the recording is in the CLOSED state

Determines how much data is kept for the stream.

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.

The size is measured in bytes.

Parameters

maxSize:long

the amount of data to retain, 0 if infinite

Exceptions

IllegalArgumentException:

if maxSize is negative

IllegalStateException:

if the recording is in CLOSED state

Implements jdk.jfr.consumer.EventStream.setOrdered.

Doc from jdk.jfr.consumer.EventStream.setOrdered.

Specifies that events arrive in chronological order, sorted by the time they were committed to the stream.

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.setReuse.

Doc from jdk.jfr.consumer.EventStream.setReuse.

Specifies that the event object in an onEvent(Consumer) action can be reused.

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

Annotations

@Override

Replaces all settings for this recording stream.

The following example records 20 seconds using the "default" configuration and then changes settings to the "profile" configuration.

Configuration defaultConfiguration = Configuration.getConfiguration("default");
Configuration profileConfiguration = Configuration.getConfiguration("profile");
try (var rs = new RecordingStream(defaultConfiguration)) {
    rs.onEvent(System.out::println);
    rs.startAsync();
    Thread.sleep(20_000);
    rs.setSettings(profileConfiguration.getSettings());
    Thread.sleep(20_000);
}

Parameters

settings:Map<String, String>

the settings to set, not null

See Also

Recording#setSettings(Map)

Implements jdk.jfr.consumer.EventStream.setStartTime.

Doc from jdk.jfr.consumer.EventStream.setStartTime.

Specifies the start time of the stream.

The start time must be set before starting the stream

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.start.

Doc from jdk.jfr.consumer.EventStream.start.

Starts processing of actions.

Actions are performed in the current thread.

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

Annotations

@Override

Implements jdk.jfr.consumer.EventStream.startAsync.

Starts asynchronous processing of actions.

Actions are performed in a single separate thread.

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

The following example prints the CPU usage for ten seconds. When the current thread leaves the try-with-resources block the stream is stopped/closed.

try (var stream = new RecordingStream()) {
    stream.enable("jdk.CPULoad").withPeriod(Duration.ofSeconds(1));
    stream.onEvent("jdk.CPULoad", event -> {
        System.out.println(event);
    });
    stream.startAsync();
    Thread.sleep(10_000);
}

Annotations

@Override

Exceptions

IllegalStateException:

if the stream is already started or closed

Stops the recording stream.

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:

AtomicBoolean socketUse = new AtomicBoolean();
try (var r = new RecordingStream()) {
    r.setMaxSize(Long.MAX_VALUE);
    r.enable("jdk.SocketWrite").withoutThreshold();
    r.enable("jdk.SocketRead").withoutThreshold();
    r.onEvent(event -> socketUse.set(true));
    r.startAsync();
    testFoo();
    r.stop();
    if (socketUse.get()) {
        r.dump(Path.of("socket-events.jfr"));
        throw new AssertionError("testFoo() should not use network");
    }
}

Returns:boolean

true if recording is stopped, false otherwise

Exceptions

IllegalStateException:

if the recording is not started or is already stopped

Since

20