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

Copy

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.