- All Implemented Interfaces:
- AutoCloseable,- EventStream
EventStream that can serialize events over
 the network using an MBeanServerConnection.
 The following example shows how to record garbage collection pauses and CPU usage on a remote host and print the events to standard out.
     
     String host = "com.example";
     int port = 4711;
     String url = "service:jmx:rmi:///jndi/rmi://" + host + ":" + port + "/jmxrmi";
     JMXServiceURL u = new JMXServiceURL(url);
     JMXConnector c = JMXConnectorFactory.connect(u);
     MBeanServerConnection conn = c.getMBeanServerConnection();
     try (var rs = new RemoteRecordingStream(conn)) {
         rs.enable("jdk.GCPhasePause").withoutThreshold();
         rs.enable("jdk.CPULoad").withPeriod(Duration.ofSeconds(1));
         rs.onEvent("jdk.CPULoad", System.out::println);
         rs.onEvent("jdk.GCPhasePause", System.out::println);
         rs.start();
     }
     
 - Since:
- 16
- 
Constructor SummaryConstructorsConstructorDescriptionRemoteRecordingStream(MBeanServerConnection connection) Creates an event stream that operates against aMBeanServerConnectionthat has a registeredFlightRecorderMXBean.RemoteRecordingStream(MBeanServerConnection connection, Path directory) Creates an event stream that operates against aMBeanServerConnectionthat has a registeredFlightRecorderMXBean.
- 
Method SummaryModifier and TypeMethodDescriptionvoidBlocks until all actions are completed, or the stream is closed, or the current thread is interrupted, whichever happens first.voidawaitTermination(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.voidclose()Releases all resources associated with this stream.Disables event with the specified name.voidWrites recording data to a file.Enables the event with the specified name.voidRegisters an action to perform when the stream is closed.voidRegisters an action to perform if an exception occurs.voidonEvent(String eventName, Consumer<RecordedEvent> action) Registers an action to perform on all events matching a name.voidonEvent(Consumer<RecordedEvent> action) Registers an action to perform on all events in the stream.voidRegisters an action to perform after the stream has been flushed.booleanUnregisters an action.voidsetEndTime(Instant endTime) Specifies the end time of the stream.voidDetermines how far back data is kept for the stream.voidsetMaxSize(long maxSize) Determines how much data is kept for the stream.voidsetOrdered(boolean ordered) Specifies that events arrives in chronological order, sorted by the time they were committed to the stream.voidsetReuse(boolean reuse) Specifies that the event object in anEventStream.onEvent(Consumer)action can be reused.voidsetSettings(Map<String, String> settings) Replaces all settings for this recording stream.voidsetStartTime(Instant startTime) Specifies the start time of the stream.voidstart()Starts processing of actions.voidStarts asynchronous processing of actions.booleanstop()Stops the recording stream.Methods declared in class java.lang.Objectclone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, waitMethods declared in interface jdk.jfr.consumer.EventStreamonMetadata
- 
Constructor Details- 
RemoteRecordingStreamCreates an event stream that operates against aMBeanServerConnectionthat has a registeredFlightRecorderMXBean.To configure event settings, use setSettings(Map).- Parameters:
- connection- the- MBeanServerConnectionwhere the- FlightRecorderMXBeanis registered, not- null
- Throws:
- IOException- if a stream can't be opened, an I/O error occurs when trying to access the repository or the- FlightRecorderMXBean
- SecurityException- if a security manager exists and its- checkReadmethod denies read access to the directory, or files in the directory.
 
- 
RemoteRecordingStreamCreates an event stream that operates against aMBeanServerConnectionthat has a registeredFlightRecorderMXBean.To configure event settings, use setSettings(Map).- Parameters:
- connection- the- MBeanServerConnectionwhere the- FlightRecorderMXBeanis registered, not- null
- directory- the directory to store event data that is downloaded, not- null
- Throws:
- IOException- if a stream can't be opened, an I/O error occurs when trying to access the repository or the- FlightRecorderMXBean
- SecurityException- if a security manager exists and its- checkReadmethod denies read access to the directory, or files in the directory.
 
 
- 
- 
Method Details- 
setSettingsReplaces all settings for this recording stream.The following example connects to a remote host and stream events using settings from the "default" configuration. { String host = "com.example"; int port = 4711; String url = "service:jmx:rmi:///jndi/rmi://" + host + ":" + port + "/jmxrmi"; JMXServiceURL u = new JMXServiceURL(url); JMXConnector c = JMXConnectorFactory.connect(u); MBeanServerConnection conn = c.getMBeanServerConnection(); try (final var rs = new RemoteRecordingStream(conn)) { rs.onMetadata(e -> { for (Configuration c : e.getConfigurations()) { if (c.getName().equals("default")) { rs.setSettings(c.getSettings()); } } }); rs.onEvent(System.out::println); rs.start(); }- Parameters:
- settings- the settings to set, not- null
- See Also:
 
- 
disableDisables 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. - Parameters:
- name- the settings for the event, not- null
- Returns:
- an event setting for further configuration, not null
 
- 
enableEnables 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. - Parameters:
- name- the settings for the event, not- null
- Returns:
- an event setting for further configuration, not null
- See Also:
 
- 
setMaxAgeDetermines 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 not consumed. - Parameters:
- maxAge- the length of time that data is kept, or- nullif infinite
- Throws:
- IllegalArgumentException- if- maxAgeis negative
- IllegalStateException- if the recording is in the- CLOSEDstate
 
- 
setMaxSizepublic 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 if events are not consumed. The size is measured in bytes. - Parameters:
- maxSize- the amount of data to retain,- 0if infinite
- Throws:
- IllegalArgumentException- if- maxSizeis negative
- IllegalStateException- if the recording is in- CLOSEDstate
 
- 
onEventDescription copied from interface:EventStreamRegisters 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:
- onEventin interface- EventStream
- Parameters:
- action- an action to perform on each- RecordedEvent, not- null
- See Also:
 
- 
onEventDescription copied from interface:EventStreamRegisters an action to perform on all events matching a name.- Specified by:
- onEventin interface- EventStream
- Parameters:
- eventName- the name of the event, not- null
- action- an action to perform on each- RecordedEventmatching the event name, not- null
 
- 
onFlushDescription copied from interface:EventStreamRegisters an action to perform after the stream has been flushed.- Specified by:
- onFlushin interface- EventStream
- Parameters:
- action- an action to perform after the stream has been flushed, not- null
 
- 
onErrorDescription copied from interface:EventStreamRegisters 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:
- onErrorin interface- EventStream
- Parameters:
- action- an action to perform if an exception occurs, not- null
 
- 
onCloseDescription copied from interface:EventStreamRegisters 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:
- onClosein interface- EventStream
- Parameters:
- action- an action to perform after the stream is closed, not- null
- See Also:
 
- 
closepublic void close()Description copied from interface:EventStreamReleases 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. - Specified by:
- closein interface- AutoCloseable
- Specified by:
- closein interface- EventStream
 
- 
removeDescription copied from interface:EventStreamUnregisters an action.If the action has been registered multiple times, all instances are unregistered. - Specified by:
- removein interface- EventStream
- Parameters:
- action- the action to unregister, not- null
- Returns:
- trueif the action was unregistered,- falseotherwise
- See Also:
 
- 
setReusepublic void setReuse(boolean reuse) Description copied from interface:EventStreamSpecifies 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:
- setReusein interface- EventStream
- Parameters:
- reuse-- trueif an event object can be reused,- falseotherwise
 
- 
setOrderedpublic void setOrdered(boolean ordered) Description copied from interface:EventStreamSpecifies that events arrives in chronological order, sorted by the time they were committed to the stream.- Specified by:
- setOrderedin interface- EventStream
- Parameters:
- ordered- if event objects arrive in chronological order to- EventStream.onEvent(Consumer)
 
- 
setStartTimeDescription copied from interface:EventStreamSpecifies the start time of the stream.The start time must be set before starting the stream - Specified by:
- setStartTimein interface- EventStream
- Parameters:
- startTime- the start time, not- null
- See Also:
 
- 
setEndTimeDescription copied from interface:EventStreamSpecifies 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:
- setEndTimein interface- EventStream
- Parameters:
- endTime- the end time, not- null
- See Also:
 
- 
startpublic void start()Description copied from interface:EventStreamStarts processing of actions.Actions are performed in the current thread. To stop the stream, use the EventStream.close()method.- Specified by:
- startin interface- EventStream
 
- 
startAsyncpublic void startAsync()Description copied from interface:EventStreamStarts asynchronous processing of actions.Actions are performed in a single separate thread. To stop the stream, use the EventStream.close()method.- Specified by:
- startAsyncin interface- EventStream
 
- 
stoppublic 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:AtomicLong bytesWritten = new AtomicLong(); try (var r = new RemoteRecordingStream(connection)) { r.setMaxSize(Long.MAX_VALUE); r.enable("jdk.FileWrite").withoutThreshold(); r.onEvent(event -> bytesWritten.addAndGet(event.getLong("bytesWritten")) ); r.startAsync(); testFoo(); r.stop(); if (bytesWritten.get() > 1_000_000L) { r.dump(Path.of("file-write-events.jfr")); throw new AssertionError("testFoo() writes too much data to disk"); } }- Returns:
- trueif recording is stopped,- falseotherwise
- Throws:
- IllegalStateException- if the recording is not started or is already stopped
- Since:
- 20
 
- 
dumpWrites 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, not- null
- 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 have- FilePermissionto write to the destination path
- Since:
- 17
- See Also:
 
- 
awaitTerminationDescription copied from interface:EventStreamBlocks 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:
- awaitTerminationin interface- EventStream
- Parameters:
- timeout- the maximum time to wait, not- null
- Throws:
- InterruptedException- if interrupted while waiting
- See Also:
 
- 
awaitTerminationDescription copied from interface:EventStreamBlocks until all actions are completed, or the stream is closed, or the current thread is interrupted, whichever happens first.- Specified by:
- awaitTerminationin interface- EventStream
- Throws:
- InterruptedException- if interrupted while waiting
- See Also:
 
 
-