OpenJDK 27 · jdk.jfr.consumer.EventStream · APIdia, the JavaDoc alternative

Represents a stream of events.

A stream is a sequence of events and the way to interact with a stream is to register actions. The EventStream interface is not to be implemented and future versions of the JDK may prevent this completely.

To receive a notification when an event arrives, register an action using the onEvent(Consumer) method. To filter the stream for an event with a specific name, use onEvent(String, Consumer) method.

By default, the same RecordedEvent object can be used to represent two or more distinct events. That object can be delivered multiple times to the same action as well as to other actions. To use an event object after the action is completed, the setReuse(boolean) method should be set to false so a new object is allocated for each event.

Events are delivered in batches. To receive a notification when a batch is complete, register an action using the onFlush(Runnable) method. This is an opportunity to aggregate or push data to external systems while the Java Virtual Machine (JVM) is preparing the next batch.

Events within a batch are sorted chronologically by their end time. Well-ordering of events is only maintained for events available to the JVM at the point of flush, i.e. for the set of events delivered as a unit in a single batch. Events delivered in a batch could therefore be out-of-order compared to events delivered in a previous batch, but never out-of-order with events within the same batch. If ordering is not a concern, sorting can be disabled using the setOrdered(boolean) method.

To dispatch events to registered actions, the stream must be started. To start processing in the current thread, invoke the start() method. To process actions asynchronously in a separate thread, invoke the startAsync() method. To await completion of the stream, use the awaitTermination awaitTermination() or the awaitTermination(Duration) method.

When a stream ends it is automatically closed. To manually stop processing of events, close the stream by invoking the close() method. A stream can also be automatically closed in exceptional circumstances, for example if the JVM that is being monitored exits. To receive a notification in any of these occasions, use the onClose(Runnable) method to register an action.

If an unexpected exception occurs in an action, it is possible to catch the exception in an error handler. An error handler can be registered using the onError(Consumer) method. If no error handler is registered, the default behavior is to print the exception and its backtrace to the standard error stream.

The following example shows how an EventStream can be used to listen to events on a JVM running Flight Recorder

try (var es = EventStream.openRepository()) {
    es.onEvent("jdk.CPULoad", event -> {
        System.out.println("CPU Load " + event.getEndTime());
        System.out.println(" Machine total: " + 100 * event.getFloat("machineTotal") + "%");
        System.out.println(" JVM User: " + 100 * event.getFloat("jvmUser") + "%");
        System.out.println(" JVM System: " + 100 * event.getFloat("jvmSystem") + "%");
        System.out.println();
    });
    es.onEvent("jdk.GarbageCollection", event -> {
        System.out.println("Garbage collection: " + event.getLong("gcId"));
        System.out.println(" Cause: " + event.getString("cause"));
        System.out.println(" Total pause: " + event.getDuration("sumOfPauses"));
        System.out.println(" Longest pause: " + event.getDuration("longestPause"));
        System.out.println();
    });
    es.start();
}

To start recording together with the stream, see RecordingStream.

Method Summary

Modifier and Type	Method and Description
public void	awaitTermination(Duration the maximum time to wait, not `null` timeout) Blocks until all actions are completed, or the stream is closed, or the timeout occurs, or the current thread is interrupted, whichever happens first.
public void	awaitTermination() Blocks until all actions are completed, or the stream is closed, or the current thread is interrupted, whichever happens first.
public void	close() Redeclares java.lang.AutoCloseable.close. Releases all resources associated with this stream.
public void	onClose(Runnable an action to perform after the stream is closed, not `null` action) Registers an action to perform when the stream is closed.
public void	onError(Consumer<Throwable> an action to perform if an exception occurs, not `null` action) Registers an action to perform if an exception occurs.
public void	onEvent(Consumer<RecordedEvent> an action to perform on each `RecordedEvent`, not `null` action) Registers an action to perform on all events in the stream.
public void	onEvent(String the name of the event, not `null` eventName, Consumer<RecordedEvent> an action to perform on each `RecordedEvent` matching the event name, not `null` action) Registers an action to perform on all events matching a name.
public void	onFlush(Runnable an action to perform after the stream has been flushed, not `null` action) Registers an action to perform after the stream has been flushed.
public default void	onMetadata(Consumer<MetadataEvent> to perform, not `null` action) Registers an action to perform when new metadata arrives in the stream.
public static EventStream	Returns: an event stream, not `null` openFile(Path location of the file, not `null` file) Creates an event stream from a file.
public static EventStream	Returns: an event stream, not `null` openRepository() Creates a stream from the repository of the current Java Virtual Machine (JVM).
public static EventStream	Returns: an event stream, not `null` openRepository(Path location of the disk repository, not `null` directory) Creates an event stream from a disk repository.
public boolean	Returns: `true` if the action was unregistered, `false` otherwise remove(Object the action to unregister, not `null` action) Unregisters an action.
public void	setEndTime(Instant the end time, not `null` endTime) Specifies the end time of the stream.
public void	setOrdered(boolean if event objects arrive in chronological order to `onEvent(Consumer)` ordered) Specifies that events arrive in chronological order, sorted by the time they were committed to the stream.
public void	setReuse(boolean `true` if an event object can be reused, `false` otherwise reuse) Specifies that the event object in an `onEvent(Consumer)` action can be reused.
public void	setStartTime(Instant the start time, not `null` startTime) Specifies the start time of the stream.
public void	start() Starts processing of actions.
public void	startAsync() Starts asynchronous processing of actions.

Method Detail

awaitTermination back to summary

awaitTermination	back to summary
public void awaitTermination(Duration timeout) throws InterruptedException Blocks until all actions are completed, or the stream is closed, or the timeout occurs, or the current thread is interrupted, whichever happens first. Parameters timeout:Duration the maximum time to wait, not `null` Exceptions InterruptedException: if interrupted while waiting IllegalArgumentException: if timeout is negative See Also `start()`, `startAsync()`, `Thread#interrupt()`

public void awaitTermination(Duration timeout) throws InterruptedException

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

Parameters

timeout:Duration: the maximum time to wait, not null

Exceptions

InterruptedException:: if interrupted while waiting
IllegalArgumentException:: if timeout is negative

awaitTermination back to summary

awaitTermination	back to summary
public void awaitTermination() throws InterruptedException Blocks until all actions are completed, or the stream is closed, or the current thread is interrupted, whichever happens first. Exceptions InterruptedException: if interrupted while waiting See Also `start()`, `startAsync()`, `Thread#interrupt()`

public void awaitTermination() throws InterruptedException

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

Exceptions

InterruptedException:: if interrupted while waiting

close	back to summary
public void close() Redeclares java.lang.AutoCloseable.close. Releases all resources associated with this stream. 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. Annotations @Override

back to summary

public void close()

Redeclares java.lang.AutoCloseable.close.

Releases all resources associated with this stream.

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.

Annotations

@Override

onClose back to summary

onClose	back to summary
public void onClose(Runnable action) 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. Parameters action:Runnable an action to perform after the stream is closed, not `null` See Also `close()`

public void onClose(Runnable action)

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.

Parameters

action:Runnable: an action to perform after the stream is closed, not null

See Also

close()

onError back to summary

onError	back to summary
public void onError(Consumer<Throwable> action) 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. Parameters action:Consumer<Throwable> an action to perform if an exception occurs, not `null`

public void onError(Consumer<Throwable> action)

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.

Parameters

action:Consumer<Throwable>: an action to perform if an exception occurs, not null

onEvent back to summary

onEvent	back to summary
public void onEvent(Consumer<RecordedEvent> action) 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. Parameters action:Consumer<RecordedEvent> an action to perform on each `RecordedEvent`, not `null` See Also `onEvent(Consumer)`, `onMetadata(Consumer)`

public void onEvent(Consumer<RecordedEvent> action)

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.

Parameters

action:Consumer<RecordedEvent>: an action to perform on each RecordedEvent, not null

onEvent back to summary

onEvent	back to summary
public void onEvent(String eventName, Consumer<RecordedEvent> action) Registers an action to perform on all events matching a name. Parameters eventName:String the name of the event, not `null` action:Consumer<RecordedEvent> an action to perform on each `RecordedEvent` matching the event name, not `null`

public void onEvent(String eventName, Consumer<RecordedEvent> action)

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

Parameters

eventName:String: the name of the event, not null
action:Consumer<RecordedEvent>: an action to perform on each RecordedEvent matching the event name, not null

onFlush back to summary

onFlush	back to summary
public void onFlush(Runnable action) Registers an action to perform after the stream has been flushed. Parameters action:Runnable an action to perform after the stream has been flushed, not `null`

public void onFlush(Runnable action)

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

Parameters

action:Runnable: an action to perform after the stream has been flushed, not null

onMetadata back to summary

public default void onMetadata(Consumer<MetadataEvent> action)

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 IOException {
    Path file = Path.of(args[0]);
    String regExp = args[1];
    var pr = Pattern.compile(regExp).asMatchPredicate();
    try (var s = EventStream.openFile(file)) {
        s.setOrdered(false);
        s.onMetadata(metadata -> metadata.getAddedEventTypes()
         .stream().map(EventType::getName).filter(pr)
         .forEach(eventName -> s.onEvent(eventName, event -> count++)));
        s.start();
        System.out.println(count + " events matches " + regExp);
    }
}

Implementation Specification

The default implementation of this method is empty.

Parameters

action:Consumer<MetadataEvent>: to perform, not null

Exceptions

IllegalStateException:: if an action is added after the stream has started

Since

openFile back to summary

openFile	back to summary
public static EventStream openFile(Path file) throws IOException Creates an event stream from a file. By default, the stream starts with the first event in the file. Only recording files from trusted sources should be opened. Parameters file:Path location of the file, not `null` Returns:EventStream an event stream, not `null` Exceptions IOException: if the file can't be opened, or an I/O error occurs during reading

public static EventStream openFile(Path file) throws IOException

Creates an event stream from a file.

By default, the stream starts with the first event in the file.

Only recording files from trusted sources should be opened.

Parameters

file:Path: location of the file, not null

Returns:EventStream

an event stream, not null

Exceptions

IOException:: if the file can't be opened, or an I/O error occurs during reading

openRepository back to summary

openRepository	back to summary
public static EventStream openRepository() throws IOException Creates a stream from the repository of the current Java Virtual Machine (JVM). By default, the stream starts with the next event flushed by Flight Recorder. Returns:EventStream an event stream, not `null` Exceptions IOException: if a stream can't be opened, or an I/O error occurs when trying to access the repository

public static EventStream openRepository() throws IOException

Creates a stream from the repository of the current Java Virtual Machine (JVM).

By default, the stream starts with the next event flushed by Flight Recorder.

Returns:EventStream

an event stream, not null

Exceptions

IOException:: if a stream can't be opened, or an I/O error occurs when trying to access the repository

openRepository back to summary

openRepository	back to summary
public static EventStream openRepository(Path directory) throws IOException Creates an event stream from a disk repository. By default, the stream starts with the next event flushed by Flight Recorder. Only trusted disk repositories should be opened. Parameters directory:Path location of the disk repository, not `null` Returns:EventStream an event stream, not `null` Exceptions IOException: if a stream can't be opened, or an I/O error occurs when trying to access the repository

public static EventStream openRepository(Path directory) throws IOException

Creates an event stream from a disk repository.

By default, the stream starts with the next event flushed by Flight Recorder.

Only trusted disk repositories should be opened.

Parameters

directory:Path: location of the disk repository, not null

Returns:EventStream

an event stream, not null

Exceptions

IOException:: if a stream can't be opened, or an I/O error occurs when trying to access the repository

remove back to summary

remove	back to summary
public boolean remove(Object action) Unregisters an action. If the action has been registered multiple times, all instances are unregistered. Parameters action:Object the action to unregister, not `null` Returns:boolean `true` if the action was unregistered, `false` otherwise See Also `onEvent(Consumer)`, `onEvent(String, Consumer)`, `onFlush(Runnable)`, `onClose(Runnable)`, `onError(Consumer)`

public boolean remove(Object action)

Unregisters an action.

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

Parameters

action:Object: the action to unregister, not null

Returns:boolean

true if the action was unregistered, false otherwise

setEndTime back to summary

setEndTime	back to summary
public void setEndTime(Instant endTime) Specifies the end time of the stream. The end time must be set before starting the stream. At end time, the stream is closed. Parameters endTime:Instant the end time, not `null` Exceptions IllegalStateException: if the stream is already started See Also `start()`, `startAsync()`

public void setEndTime(Instant endTime)

Specifies the end time of the stream.

The end time must be set before starting the stream.

At end time, the stream is closed.

Parameters

endTime:Instant: the end time, not null

Exceptions

IllegalStateException:: if the stream is already started

See Also

start(), startAsync()

setOrdered back to summary

setOrdered	back to summary
public void setOrdered(boolean ordered) Specifies that events arrive in chronological order, sorted by the time they were committed to the stream. Parameters ordered:boolean if event objects arrive in chronological order to `onEvent(Consumer)`

public void setOrdered(boolean ordered)

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

Parameters

ordered:boolean: if event objects arrive in chronological order to onEvent(Consumer)

setReuse back to summary

setReuse	back to summary
public void setReuse(boolean reuse) 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. Parameters reuse:boolean `true` if an event object can be reused, `false` otherwise

public void setReuse(boolean reuse)

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.

Parameters

reuse:boolean: true if an event object can be reused, false otherwise

setStartTime back to summary

setStartTime	back to summary
public void setStartTime(Instant startTime) Specifies the start time of the stream. The start time must be set before starting the stream Parameters startTime:Instant the start time, not `null` Exceptions IllegalStateException: if the stream is already started See Also `start()`, `startAsync()`

public void setStartTime(Instant startTime)

Specifies the start time of the stream.

The start time must be set before starting the stream

Parameters

startTime:Instant: the start time, not null

Exceptions

IllegalStateException:: if the stream is already started

See Also

start(), startAsync()

start back to summary

start	back to summary
public void start() Starts processing of actions. Actions are performed in the current thread. To stop the stream, use the `close()` method. Exceptions IllegalStateException: if the stream is already started or closed

public void start()

Starts processing of actions.

Actions are performed in the current thread.

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

Exceptions

IllegalStateException:: if the stream is already started or closed

startAsync back to summary

startAsync	back to summary
public void startAsync() Starts asynchronous processing of actions. Actions are performed in a single separate thread. To stop the stream, use the `close()` method. Exceptions IllegalStateException: if the stream is already started or closed

public void startAsync()

Starts asynchronous processing of actions.

Actions are performed in a single separate thread.

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

Exceptions

IllegalStateException:: if the stream is already started or closed

public Interface EventStream

Method Summary

Method Detail