Class RecordingStream

public RecordingStream()

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

public RecordingStream(Configuration configuration)

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();
 }
 

public EventSettings enable(String name)

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.

public void setSettings(Map<String,String> settings)

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);
 }
 

public EventSettings enable(Class<? extends Event> eventClass)

Enables event.

public EventSettings disable(String name)

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.

public EventSettings disable(Class<? extends Event> eventClass)

Disables event.

public void setMaxAge(Duration maxAge)

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

public void setMaxSize(long maxSize)

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.

public void setReuse(boolean reuse)

Specifies that the event object in an EventStream.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.

public void setOrdered(boolean ordered)

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

public void setStartTime(Instant startTime)

Specifies the start time of the stream.

The start time must be set before starting the stream

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.

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

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

public void onEvent(Consumer<RecordedEvent> action)

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

public void onFlush(Runnable action)

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

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.

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.

public void close()

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

public boolean remove(Object action)

Unregisters an action.

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

public void start()

Starts processing of actions.

Actions are performed in the current thread.

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

public void 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);
 }
 

public void dump(Path destination) throws IOException

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.

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.

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.