- All Implemented Interfaces:
AutoCloseable
,EventStream
The following example shows how to record events using the default configuration and print the Garbage Collection, CPU Load and JVM Information event to standard out.
Configuration c = Configuration.getConfiguration("default");
try (var rs = new RecordingStream(c)) {
rs.onEvent("jdk.GarbageCollection", System.out::println);
rs.onEvent("jdk.CPULoad", System.out::println);
rs.onEvent("jdk.JVMInformation", System.out::println);
rs.start();
}
- Since:
- 14
-
Constructor Summary
ConstructorDescriptionCreates an event stream for the current JVM (Java Virtual Machine).RecordingStream
(Configuration configuration) Creates a recording stream using settings from a configuration. -
Method Summary
Modifier and TypeMethodDescriptionvoid
Blocks until all actions are completed, or the stream is closed, or the current thread is interrupted, whichever happens first.void
awaitTermination
(Duration 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.void
close()
Closes this resource, relinquishing any underlying resources.Disables event.Disables event with the specified name.void
Writes recording data to a file.Enables event.Enables the event with the specified name.void
Registers an action to perform when the stream is closed.void
Registers an action to perform if an exception occurs.void
onEvent
(String eventName, Consumer<RecordedEvent> action) Registers an action to perform on all events matching a name.void
onEvent
(Consumer<RecordedEvent> action) Registers an action to perform on all events in the stream.void
Registers an action to perform after the stream has been flushed.boolean
Unregisters an action.void
setEndTime
(Instant endTime) Specifies the end time of the stream.void
Determines how far back data is kept for the stream.void
setMaxSize
(long maxSize) Determines how much data is kept for the stream.void
setOrdered
(boolean ordered) Specifies that events arrives in chronological order, sorted by the time they were committed to the stream.void
setReuse
(boolean reuse) Specifies that the event object in anEventStream.onEvent(Consumer)
action can be reused.void
setSettings
(Map<String, String> settings) Replaces all settings for this recording stream.void
setStartTime
(Instant startTime) Specifies the start time of the stream.void
start()
Starts processing of actions.void
Starts asynchronous processing of actions.boolean
stop()
Stops the recording stream.Methods declared in class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods declared in interface jdk.jfr.consumer.EventStream
onMetadata
-
Constructor Details
-
RecordingStream
public RecordingStream()Creates an event stream for the current JVM (Java Virtual Machine).- Throws:
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)SecurityException
- if a security manager exists and the caller does not haveFlightRecorderPermission("accessFlightRecorder")
-
RecordingStream
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 that contains the settings to use, notnull
- Throws:
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)SecurityException
- if a security manager is used and FlightRecorderPermission "accessFlightRecorder" is not set.- See Also:
-
-
Method Details
-
enable
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 aString
representation of the event type ID.- Parameters:
name
- the settings for the event, notnull
- Returns:
- an event setting for further configuration, not
null
- See Also:
-
setSettings
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
- the settings to set, notnull
- See Also:
-
enable
Enables event.- Parameters:
eventClass
- the event to enable, notnull
- Returns:
- an event setting for further configuration, not
null
- Throws:
IllegalArgumentException
- ifeventClass
is an abstract class or not a subclass ofEvent
-
disable
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 aString
representation of the event type ID.- Parameters:
name
- the settings for the event, notnull
- Returns:
- an event setting for further configuration, not
null
-
disable
Disables event.- Parameters:
eventClass
- the event to enable, notnull
- Returns:
- an event setting for further configuration, not
null
- Throws:
IllegalArgumentException
- ifeventClass
is an abstract class or not a subclass ofEvent
-
setMaxAge
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
- Parameters:
maxAge
- the length of time that data is kept, ornull
if infinite- Throws:
IllegalArgumentException
- ifmaxAge
is negativeIllegalStateException
- if the recording is in theCLOSED
state
-
setMaxSize
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.
- Parameters:
maxSize
- the amount of data to retain,0
if infinite- Throws:
IllegalArgumentException
- ifmaxSize
is negativeIllegalStateException
- if the recording is inCLOSED
state
-
setReuse
public void setReuse(boolean reuse) Description copied from interface:EventStream
Specifies that the event object in anEventStream.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.- Specified by:
setReuse
in interfaceEventStream
- Parameters:
reuse
-true
if an event object can be reused,false
otherwise
-
setOrdered
public void setOrdered(boolean ordered) Description copied from interface:EventStream
Specifies that events arrives in chronological order, sorted by the time they were committed to the stream.- Specified by:
setOrdered
in interfaceEventStream
- Parameters:
ordered
- if event objects arrive in chronological order toEventStream.onEvent(Consumer)
-
setStartTime
Description copied from interface:EventStream
Specifies the start time of the stream.The start time must be set before starting the stream
- Specified by:
setStartTime
in interfaceEventStream
- Parameters:
startTime
- the start time, notnull
- See Also:
-
setEndTime
Description copied from interface:EventStream
Specifies the end time of the stream.The end time must be set before starting the stream.
At end time, the stream is closed.
- Specified by:
setEndTime
in interfaceEventStream
- Parameters:
endTime
- the end time, notnull
- See Also:
-
onEvent
Description copied from interface:EventStream
Registers an action to perform on all events matching a name.- Specified by:
onEvent
in interfaceEventStream
- Parameters:
eventName
- the name of the event, notnull
action
- an action to perform on eachRecordedEvent
matching the event name, notnull
-
onEvent
Description copied from interface:EventStream
Registers an action to perform on all events in the stream.To perform an action on a subset of event types, consider using
EventStream.onEvent(String, Consumer)
andEventStream.onMetadata(Consumer)
as it is likely more performant than any selection or filtering mechanism implemented in a generic action.- Specified by:
onEvent
in interfaceEventStream
- Parameters:
action
- an action to perform on eachRecordedEvent
, notnull
- See Also:
-
onFlush
Description copied from interface:EventStream
Registers an action to perform after the stream has been flushed.- Specified by:
onFlush
in interfaceEventStream
- Parameters:
action
- an action to perform after the stream has been flushed, notnull
-
onClose
Description copied from interface:EventStream
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.
- Specified by:
onClose
in interfaceEventStream
- Parameters:
action
- an action to perform after the stream is closed, notnull
- See Also:
-
onError
Description copied from interface:EventStream
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.
- Specified by:
onError
in interfaceEventStream
- Parameters:
action
- an action to perform if an exception occurs, notnull
-
close
public void close()Description copied from interface:AutoCloseable
Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by thetry
-with-resources statement.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceEventStream
-
remove
Description copied from interface:EventStream
Unregisters an action.If the action has been registered multiple times, all instances are unregistered.
- Specified by:
remove
in interfaceEventStream
- Parameters:
action
- the action to unregister, notnull
- Returns:
true
if the action was unregistered,false
otherwise- See Also:
-
start
public void start()Description copied from interface:EventStream
Starts processing of actions.Actions are performed in the current thread.
To stop the stream, use the
EventStream.close()
method.- Specified by:
start
in interfaceEventStream
-
startAsync
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); }
- Specified by:
startAsync
in interfaceEventStream
- Throws:
IllegalStateException
- if the stream is already started or closed
-
stop
public boolean stop()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 theclose()
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:
true
if recording is stopped,false
otherwise- Throws:
IllegalStateException
- if the recording is not started or is already stopped- Since:
- 20
-
dump
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
- the location where recording data is written, notnull
- Throws:
IOException
- if the recording data can't be copied to the specified location, or if the stream is closed, or not started.SecurityException
- if a security manager exists and the caller doesn't haveFilePermission
to write to the destination path- Since:
- 17
- See Also:
-
awaitTermination
Description copied from interface:EventStream
Blocks until all actions are completed, or the stream is closed, or the timeout occurs, or the current thread is interrupted, whichever happens first.- Specified by:
awaitTermination
in interfaceEventStream
- Parameters:
timeout
- the maximum time to wait, notnull
- Throws:
InterruptedException
- if interrupted while waiting- See Also:
-
awaitTermination
Description copied from interface:EventStream
Blocks until all actions are completed, or the stream is closed, or the current thread is interrupted, whichever happens first.- Specified by:
awaitTermination
in interfaceEventStream
- Throws:
InterruptedException
- if interrupted while waiting- See Also:
-