* The following example shows how configure, start, stop and dump recording data to disk. * *
*
* Configuration c = Configuration.getConfiguration("default");
* Recording r = new Recording(c);
* r.start();
* System.gc();
* Thread.sleep(5000);
* r.stop();
* r.copyTo(Files.createTempFile("my-recording", ".jfr"));
*
*
*
* @since 9
*/
public final class Recording implements Closeable {
private static class RecordingSettings extends EventSettings {
private final Recording recording;
private final String identifier;
RecordingSettings(Recording r, String identifier) {
this.recording = r;
this.identifier = identifier;
}
RecordingSettings(Recording r, Class eventClass) {
Utils.ensureValidEventSubclass(eventClass);
this.recording = r;
this.identifier = String.valueOf(Type.getTypeId(eventClass));
}
@Override
public EventSettings with(String name, String value) {
Objects.requireNonNull(value);
recording.setSetting(identifier + "#" + name, value);
return this;
}
@Override
public Map
* A newly created recording is in the {@link RecordingState#NEW} state. To start
* the recording, invoke the {@link Recording#start()} method.
*
* @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)
*
* @throws SecurityException If a security manager is used and
* FlightRecorderPermission "accessFlightRecorder" is not set.
*/
public Recording() {
this(new HashMap
* The following example shows how create a recording that uses a predefined configuration.
*
*
* It's recommended that the recording options and event settings are configured
* before calling this method. The benefits of doing so are a more consistent
* state when analyzing the recorded data, and improved performance because the
* configuration can be applied atomically.
*
* After a successful invocation of this method, this recording is in the
* {@code RUNNING} state.
*
* @throws IllegalStateException if recording is already started or is in the
* {@code CLOSED} state
*/
public void start() {
internal.start();
}
/**
* Starts this recording after a delay.
*
* After a successful invocation of this method, this recording is in the
* {@code DELAYED} state.
*
* @param delay the time to wait before starting this recording, not
* {@code null}
* @throws IllegalStateException if the recording is not it the {@code NEW} state
*/
public void scheduleStart(Duration delay) {
Objects.requireNonNull(delay);
internal.scheduleStart(delay);
}
/**
* Stops this recording.
*
* When a recording is stopped it can't be restarted. If this
* recording has a destination, data is written to that destination and
* the recording is closed. After a recording is closed, the data is no longer
* available.
*
* After a successful invocation of this method, this recording will be
* in the {@code STOPPED} state.
*
* @return {@code true} if recording is stopped, {@code false} otherwise
*
* @throws IllegalStateException if the recording is not started or is already stopped
*
* @throws SecurityException if a security manager exists and the caller
* doesn't have {@code FilePermission} to write to the destination
* path
*
* @see #setDestination(Path)
*
*/
public boolean stop() {
return internal.stop("Stopped by user");
}
/**
* Returns settings used by this recording.
*
* Modifying the returned {@code Map} will not change the settings for this recording.
*
* If no settings are set for this recording, an empty {@code Map} is
* returned.
*
* @return recording settings, not {@code null}
*/
public Map
* The size is updated when recording buffers are flushed. If the recording is
* not written to the disk repository the returned size is always {@code 0}.
*
* @return amount of recorded data, measured in bytes, or {@code 0} if the
* recording is not written to the disk repository
*/
public long getSize() {
return internal.getSize();
}
/**
* Returns the time when this recording was stopped.
*
* @return the time, or {@code null} if this recording is not stopped
*/
public Instant getStopTime() {
return internal.getStopTime();
}
/**
* Returns the time when this recording was started.
*
* @return the the time, or {@code null} if this recording is not started
*/
public Instant getStartTime() {
return internal.getStartTime();
}
/**
* Returns the maximum size, measured in bytes, at which data is no longer kept in the disk repository.
*
* @return maximum size in bytes, or {@code 0} if no maximum size is set
*/
public long getMaxSize() {
return internal.getMaxSize();
}
/**
* Returns the length of time that the data is kept in the disk repository
* before it is removed.
*
* @return maximum length of time, or {@code null} if no maximum length of time
* has been set
*/
public Duration getMaxAge() {
return internal.getMaxAge();
}
/**
* Returns the name of this recording.
*
* By default, the name is the same as the recording ID.
*
* @return the recording name, not {@code null}
*/
public String getName() {
return internal.getName();
}
/**
* Replaces all settings for this recording.
*
* The following example shows how to set event settings for a recording.
*
*
* After a successful invocation of this method, this recording is in the
* {@code CLOSED} state.
*/
@Override
public void close() {
internal.close();
}
/**
* Returns a clone of this recording, with a new recording ID and name.
*
* Clones are useful for dumping data without stopping the recording. After
* a clone is created, the amount of data to copy is constrained
* with the {@link #setMaxAge(Duration)} method and the {@link #setMaxSize(long)}method.
*
* @param stop {@code true} if the newly created copy should be stopped
* immediately, {@code false} otherwise
* @return the recording copy, not {@code null}
*/
public Recording copy(boolean stop) {
return internal.newCopy(stop);
}
/**
* Writes recording data to a file.
*
* Recording must be started, but not necessarily stopped.
*
* @param destination the location where recording data is written, not
* {@code null}
*
* @throws IOException if the recording can't be copied to the specified
* location
*
* @throws SecurityException if a security manager exists and the caller doesn't
* have {@code FilePermission} to write to the destination path
*/
public void dump(Path destination) throws IOException {
Objects.requireNonNull(destination);
internal.dump(new WriteableUserPath(destination));
}
/**
* Returns {@code true} if this recording uses the disk repository, {@code false} otherwise.
*
* If no value is set, {@code true} is returned.
*
* @return {@code true} if the recording uses the disk repository, {@code false}
* otherwise
*/
public boolean isToDisk() {
return internal.isToDisk();
}
/**
* Determines how much data is kept in the disk repository.
*
* 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.
*
* @param maxSize the amount of data to retain, {@code 0} if infinite
*
* @throws IllegalArgumentException if
* 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.
*
* @param maxAge the length of time that data is kept, or {@code null} if infinite
*
* @throws IllegalArgumentException if
* If a destination is set, this recording is automatically closed
* after data is successfully copied to the destination path.
*
* If a destination is not set, Flight Recorder retains the
* recording data until this recording is closed. Use the {@link #dump(Path)} method to
* manually write data to a file.
*
* @param destination the destination path, or {@code null} if recording should
* not be dumped at stop
*
* @throws IllegalStateException if recording is in the {@code STOPPED} or
* {@code CLOSED} state.
*
* @throws SecurityException if a security manager exists and the caller
* doesn't have {@code FilePermission} to read, write, and delete the
* {@code destination} file
*
* @throws IOException if the path is not writable
*/
public void setDestination(Path destination) throws IOException {
internal.setDestination(destination != null ? new WriteableUserPath(destination) : null);
}
/**
* Returns the destination file, where recording data is written when the
* recording stops, or {@code null} if no destination is set.
*
* @return the destination file, or {@code null} if not set.
*/
public Path getDestination() {
WriteableUserPath usp = internal.getDestination();
if (usp == null) {
return null;
} else {
return usp.getPotentiallyMaliciousOriginal();
}
}
/**
* Returns a unique ID for this recording.
*
* @return the recording ID
*/
public long getId() {
return internal.getId();
}
/**
* Sets a human-readable name (for example, {@code "My Recording"}).
*
* @param name the recording name, not {@code null}
*
* @throws IllegalStateException if the recording is in {@code CLOSED} state
*/
public void setName(String name) {
Objects.requireNonNull(name);
internal.setName(name);
}
/**
* Sets whether this recording is dumped to disk when the JVM exits.
*
* @param dumpOnExit if this recording should be dumped when the JVM exits
*/
public void setDumpOnExit(boolean dumpOnExit) {
internal.setDumpOnExit(dumpOnExit);
}
/**
* Returns whether this recording is dumped to disk when the JVM exits.
*
* If dump on exit is not set, {@code false} is returned.
*
* @return {@code true} if the recording is dumped on exit, {@code false}
* otherwise.
*/
public boolean getDumpOnExit() {
return internal.getDumpOnExit();
}
/**
* Determines whether this recording is continuously flushed to the disk
* repository or data is constrained to what is available in memory buffers.
*
* @param disk {@code true} if this recording is written to disk,
* {@code false} if in-memory
*
*/
public void setToDisk(boolean disk) {
internal.setToDisk(disk);
}
/**
* Creates a data stream for a specified interval.
*
* The stream may contain some data outside the specified range.
*
* @param the start start time for the stream, or {@code null} to get data from
* start time of the recording
*
* @param the end end time for the stream, or {@code null} to get data until the
* present time.
*
* @return an input stream, or {@code null} if no data is available in the
* interval.
*
* @throws IllegalArgumentException if {@code end} happens before
* {@code start}
*
* @throws IOException if a stream can't be opened
*/
public InputStream getStream(Instant start, Instant end) throws IOException {
if (start != null && end != null && end.isBefore(start)) {
throw new IllegalArgumentException("End time of requested stream must not be before start time");
}
return internal.open(start, end);
}
/**
* Returns the specified duration for this recording, or {@code null} if no
* duration is set.
*
* The duration can be set only when the recording is in the
* {@link RecordingState#NEW} state.
*
* @return the desired duration of the recording, or {@code null} if no duration
* has been set.
*/
public Duration getDuration() {
return internal.getDuration();
}
/**
* Sets a duration for how long a recording runs before it stops.
*
* By default, a recording has no duration ({@code null}).
*
* @param duration the duration, or {@code null} if no duration is set
*
* @throws IllegalStateException if recording is in the {@code STOPPED} or {@code CLOSED} state
*/
public void setDuration(Duration duration) {
internal.setDuration(duration);
}
/**
* 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 {@link #enable(Class)} method or a {@code String}
* representation of the event type ID.
*
* @param name the settings for the event, not {@code null}
*
* @return an event setting for further configuration, not {@code null}
*
* @see EventType
*/
public EventSettings enable(String name) {
Objects.requireNonNull(name);
RecordingSettings rs = new RecordingSettings(this, name);
rs.with("enabled", "true");
return rs;
}
/**
* 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 is disabled. To disable a specific class, use the
* {@link #disable(Class)} method or a {@code String} representation of the event
* type ID.
*
* @param name the settings for the event, not {@code null}
*
* @return an event setting for further configuration, not {@code null}
*
*/
public EventSettings disable(String name) {
Objects.requireNonNull(name);
RecordingSettings rs = new RecordingSettings(this, name);
rs.with("enabled", "false");
return rs;
}
/**
* Enables event.
*
* @param eventClass the event to enable, not {@code null}
*
* @throws IllegalArgumentException if {@code eventClass} is an abstract
* class or not a subclass of {@link Event}
*
* @return an event setting for further configuration, not {@code null}
*/
public EventSettings enable(Class eventClass) {
Objects.requireNonNull(eventClass);
RecordingSettings rs = new RecordingSettings(this, eventClass);
rs.with("enabled", "true");
return rs;
}
/**
* Disables event.
*
* @param eventClass the event to enable, not {@code null}
*
* @throws IllegalArgumentException if {@code eventClass} is an abstract
* class or not a subclass of {@link Event}
*
* @return an event setting for further configuration, not {@code null}
*
*/
public EventSettings disable(Class eventClass) {
Objects.requireNonNull(eventClass);
RecordingSettings rs = new RecordingSettings(this, eventClass);
rs.with("enabled", "false");
return rs;
}
// package private
PlatformRecording getInternal() {
return internal;
}
private void setSetting(String id, String value) {
Objects.requireNonNull(id);
Objects.requireNonNull(value);
internal.setSetting(id, value);
}
}
*
*
* The newly created recording is in the {@link RecordingState#NEW} state. To
* start the recording, invoke the {@link Recording#start()} method.
*
* @param configuration configuration that contains the settings to be use, not
* {@code null}
*
* @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)
*
* @throws SecurityException if a security manager is used and
* FlightRecorderPermission "accessFlightRecorder" is not set.
*
* @see Configuration
*/
public Recording(Configuration configuration) {
this(configuration.getSettings());
}
/**
* Starts this recording.
*
* Recording r = new Recording(Configuration.getConfiguration("default"));
*
*
*
*
* The following example shows how to merge settings.
*
*
* Map{@literal <}String, String{@literal >} settings = new HashMap{@literal <}{@literal >}();
* settings.putAll(EventSettings.enabled("jdk.CPUSample").withPeriod(Duration.ofSeconds(2)).toMap());
* settings.putAll(EventSettings.enabled(MyEvent.class).withThreshold(Duration.ofSeconds(2)).withoutStackTrace().toMap());
* settings.put("jdk.ExecutionSample#period", "10 ms");
* recording.setSettings(settings);
*
*
* {@code
* Map
*
* @param settings the settings to set, not {@code null}
*/
public void setSettings(MapmaxSize is negative
*
* @throws IllegalStateException if the recording is in {@code CLOSED} state
*/
public void setMaxSize(long maxSize) {
if (maxSize < 0) {
throw new IllegalArgumentException("Max size of recording can't be negative");
}
internal.setMaxSize(maxSize);
}
/**
* Determines how far back data is kept in the disk repository.
* maxAge is negative
*
* @throws IllegalStateException if the recording is in the {@code CLOSED} state
*/
public void setMaxAge(Duration maxAge) {
if (maxAge != null && maxAge.isNegative()) {
throw new IllegalArgumentException("Max age of recording can't be negative");
}
internal.setMaxAge(maxAge);
}
/**
* Sets a location where data is written on recording stop, or
* {@code null} if data is not to be dumped.
*