Module jdk.jfr
Package jdk.jfr

# Class Recording

java.lang.Object
jdk.jfr.Recording

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public final class Recording extends Object implements Closeable
Provides means to configure, start, stop and dump recording data to disk.

The following example shows how configure, start, stop and dump recording data to disk.

    Configuration c = Configuration.getConfiguration("default");
    try (Recording r = new Recording(c)) {
        r.start();
        System.gc();
        Thread.sleep(5000);
        r.stop();
        r.dump(Files.createTempFile("my-recording", ".jfr"));
    }

Since:
  9

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Recording()`
  Creates a recording without any settings.
  `Recording(Map<String,String> settings)`
  Creates a recording with settings from a map of name-value pairs.
  `Recording(Configuration configuration)`
  Creates a recording with settings from a configuration.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Releases all data that is associated with this recording.
  `Recording`
  `copy(boolean stop)`
  Returns a clone of this recording, with a new recording ID and name.
  `EventSettings`
  `disable(Class<? extends Event> eventClass)`
  Disables event.
  `EventSettings`
  `disable(String name)`
  Disables event with the specified name.
  `void`
  `dump(Path destination)`
  Writes recording data to a file.
  `EventSettings`
  `enable(Class<? extends Event> eventClass)`
  Enables event.
  `EventSettings`
  `enable(String name)`
  Enables the event with the specified name.
  `Path`
  `getDestination()`
  Returns the destination file, where recording data is written when the recording stops, or `null` if no destination is set.
  `boolean`
  `getDumpOnExit()`
  Returns whether this recording is dumped to disk when the JVM exits.
  `Duration`
  `getDuration()`
  Returns the specified duration for this recording, or `null` if no duration is set.
  `long`
  `getId()`
  Returns a unique ID for this recording.
  `Duration`
  `getMaxAge()`
  Returns the length of time that the data is kept in the disk repository before it is removed.
  `long`
  `getMaxSize()`
  Returns the maximum size, measured in bytes, at which data is no longer kept in the disk repository.
  `String`
  `getName()`
  Returns the name of this recording.
  `Map<String,String>`
  `getSettings()`
  Returns settings used by this recording.
  `long`
  `getSize()`
  Returns the current size of this recording in the disk repository, measured in bytes.
  `Instant`
  `getStartTime()`
  Returns the time when this recording was started.
  `RecordingState`
  `getState()`
  Returns the recording state that this recording is currently in.
  `Instant`
  `getStopTime()`
  Returns the time when this recording was stopped.
  `InputStream`
  `getStream(Instant start, Instant end)`
  Creates a data stream for a specified interval.
  `boolean`
  `isToDisk()`
  Returns `true` if this recording uses the disk repository, `false` otherwise.
  `void`
  `scheduleStart(Duration delay)`
  Starts this recording after a delay.
  `void`
  `setDestination(Path destination)`
  Sets a location where data is written on recording stop, or `null` if data is not to be dumped.
  `void`
  `setDumpOnExit(boolean dumpOnExit)`
  Sets whether this recording is dumped to disk when the JVM exits.
  `void`
  `setDuration(Duration duration)`
  Sets a duration for how long a recording runs before it stops.
  `void`
  `setMaxAge(Duration maxAge)`
  Determines how far back data is kept in the disk repository.
  `void`
  `setMaxSize(long maxSize)`
  Determines how much data is kept in the disk repository.
  `void`
  `setName(String name)`
  Sets a human-readable name (for example, `"My Recording"`).
  `void`
  `setSettings(Map<String,String> settings)`
  Replaces all settings for this recording.
  `void`
  `setToDisk(boolean disk)`
  Determines whether this recording is continuously flushed to the disk repository or data is constrained to what is available in memory buffers.
  `void`
  `start()`
  Starts this recording.
  `boolean`
  `stop()`
  Stops this recording.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Recording

    public Recording(Map<String,String> settings)
    Creates a recording with settings from a map of name-value pairs.

    A newly created recording is in the `RecordingState.NEW` state. To start the recording, invoke the `start()` method.

    Parameters:
      `settings` - settings as a map of name-value pairs, not `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)
      `SecurityException` - If a security manager is used and FlightRecorderPermission "accessFlightRecorder" is not set.
    See Also:
      - `jdk.jfr`

  - ### Recording

    public Recording()
    Creates a recording without any settings.

    A newly created recording is in the `RecordingState.NEW` state. To start the recording, invoke the `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)
      `SecurityException` - If a security manager is used and FlightRecorderPermission "accessFlightRecorder" is not set.

  - ### Recording

    public Recording(Configuration configuration)
    Creates a recording with settings from a configuration.

    The following example shows how create a recording that uses a predefined configuration.

        Recording r = new Recording(Configuration.getConfiguration("default"));

    The newly created recording is in the `RecordingState.NEW` state. To start the recording, invoke the `start()` method.
    Parameters:
      `configuration` - configuration that contains the settings to be use, not `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)
      `SecurityException` - if a security manager is used and FlightRecorderPermission "accessFlightRecorder" is not set.
    See Also:
      - `Configuration`

- ## Method Details

  - ### start

    public void start()
    Starts this recording.

    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 `RUNNING` state.

    Throws:
      `IllegalStateException` - if recording is already started or is in the `CLOSED` state

  - ### scheduleStart

    public void scheduleStart(Duration delay)
    Starts this recording after a delay.

    After a successful invocation of this method, this recording is in the `DELAYED` state.

    Parameters:
      `delay` - the time to wait before starting this recording, not `null`
    Throws:
      `IllegalStateException` - if the recording is not it the `NEW` state

  - ### stop

    public boolean stop()
    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 `STOPPED` state.

    Returns:
      `true` if recording is stopped, `false` otherwise
    Throws:
      `IllegalStateException` - if the recording is not started or is already stopped
      `SecurityException` - if a security manager exists and the caller doesn't have `FilePermission` to write to the destination path
    See Also:
      - `setDestination(Path)`

  - ### getSettings

    public Map<String,String> getSettings()
    Returns settings used by this recording.

    Modifying the returned `Map` will not change the settings for this recording.

    If no settings are set for this recording, an empty `Map` is returned.

    Returns:
      recording settings, not `null`

  - ### getSize

    public long getSize()
    Returns the current size of this recording in the disk repository, measured in bytes.

    The size is updated when recording buffers are flushed. If the recording is not written to the disk repository the returned size is always `0`.

    Returns:
      amount of recorded data, measured in bytes, or `0` if the recording is not written to the disk repository

  - ### getStopTime

    public Instant getStopTime()
    Returns the time when this recording was stopped.
    Returns:
      the time, or `null` if this recording is not stopped

  - ### getStartTime

    public Instant getStartTime()
    Returns the time when this recording was started.
    Returns:
      the time, or `null` if this recording is not started

  - ### getMaxSize

    public long getMaxSize()
    Returns the maximum size, measured in bytes, at which data is no longer kept in the disk repository.
    Returns:
      maximum size in bytes, or `0` if no maximum size is set

  - ### getMaxAge

    public Duration getMaxAge()
    Returns the length of time that the data is kept in the disk repository before it is removed.
    Returns:
      maximum length of time, or `null` if no maximum length of time has been set

  - ### getName

    public String getName()
    Returns the name of this recording.

    By default, the name is the same as the recording ID.

    Returns:
      the recording name, not `null`

  - ### setSettings

    public void setSettings(Map<String,String> settings)
    Replaces all settings for this recording.

    The following example shows how to set event settings for a recording.

            Map<String, String> settings = new HashMap<>();
            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);

    The following example shows how to merge settings.

            Map<String, String> settings = recording.getSettings();
            settings.putAll(additionalSettings);
            recording.setSettings(settings);

    Parameters:
      `settings` - the settings to set, not `null`

  - ### getState

    public RecordingState getState()
    Returns the recording state that this recording is currently in.
    Returns:
      the recording state, not `null`
    See Also:
      - `RecordingState`

  - ### close

    public void close()
    Releases all data that is associated with this recording.

    After a successful invocation of this method, this recording is in the `CLOSED` state.

    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`

  - ### copy

    public Recording copy(boolean stop)
    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 `setMaxAge(Duration)` method and the `setMaxSize(long)`method.

    Parameters:
      `stop` - `true` if the newly created copy should be stopped immediately, `false` otherwise
    Returns:
      the recording copy, not `null`

  - ### dump

    public void dump(Path destination) throws IOException
    Writes recording data to a file.

    For a dump to succeed, the recording must either be 1) running, or 2) stopped and to disk. If the recording is in any other state, an `IOException` is thrown.

    Parameters:
      `destination` - the location where recording data is written, not `null`
    Throws:
      `IOException` - if recording data can't be copied to the specified location, for example, if the recording is closed or the destination path is not writable
      `SecurityException` - if a security manager exists and the caller doesn't have `FilePermission` to write to the destination path
    See Also:
      - `getState()`
      - `isToDisk()`

  - ### isToDisk

    public boolean isToDisk()
    Returns `true` if this recording uses the disk repository, `false` otherwise.

    If no value is set, `true` is returned.

    Returns:
      `true` if the recording uses the disk repository, `false` otherwise

  - ### setMaxSize

    public void setMaxSize(long maxSize)
    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.

    Parameters:
      `maxSize` - the amount of data to retain, `0` if infinite
    Throws:
      `IllegalArgumentException` - if `maxSize` is negative
      `IllegalStateException` - if the recording is in `CLOSED` state

  - ### setMaxAge

    public void setMaxAge(Duration maxAge)
    Determines how far back data is kept in the disk repository.

    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.

    Parameters:
      `maxAge` - the length of time that data is kept, or `null` if infinite
    Throws:
      `IllegalArgumentException` - if `maxAge` is negative
      `IllegalStateException` - if the recording is in the `CLOSED` state

  - ### setDestination

    public void setDestination(Path destination) throws IOException
    Sets a location where data is written on recording stop, or `null` if data is not to be dumped.

    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 `dump(Path)` method to manually write data to a file.

    Parameters:
      `destination` - the destination path, or `null` if recording should not be dumped at stop
    Throws:
      `IllegalStateException` - if recording is in the `STOPPED` or `CLOSED` state.
      `SecurityException` - if a security manager exists and the caller doesn't have `FilePermission` to read, write, and delete the `destination` file
      `IOException` - if the path is not writable

  - ### getDestination

    public Path getDestination()
    Returns the destination file, where recording data is written when the recording stops, or `null` if no destination is set.
    Returns:
      the destination file, or `null` if not set.

  - ### getId

    public long getId()
    Returns a unique ID for this recording.
    Returns:
      the recording ID

  - ### setName

    public void setName(String name)
    Sets a human-readable name (for example, `"My Recording"`).
    Parameters:
      `name` - the recording name, not `null`
    Throws:
      `IllegalStateException` - if the recording is in `CLOSED` state

  - ### setDumpOnExit

    public void setDumpOnExit(boolean dumpOnExit)
    Sets whether this recording is dumped to disk when the JVM exits.
    Parameters:
      `dumpOnExit` - if this recording should be dumped when the JVM exits

  - ### getDumpOnExit

    public boolean getDumpOnExit()
    Returns whether this recording is dumped to disk when the JVM exits.

    If dump on exit is not set, `false` is returned.

    Returns:
      `true` if the recording is dumped on exit, `false` otherwise.

  - ### setToDisk

    public void setToDisk(boolean disk)
    Determines whether this recording is continuously flushed to the disk repository or data is constrained to what is available in memory buffers.
    Parameters:
      `disk` - `true` if this recording is written to disk, `false` if in-memory

  - ### getStream

    public InputStream getStream(Instant start, Instant end) throws IOException
    Creates a data stream for a specified interval.

    The stream may contain some data outside the specified range.

    If the recording is not to disk, a stream can't be created and `null` is returned.

    Parameters:
      `start` - the start time for the stream, or `null` to get data from start time of the recording
      `end` - the end time for the stream, or `null` to get data until the present time.
    Returns:
      an input stream, or `null` if no data is available in the interval, or the recording was not recorded to disk
    Throws:
      `IllegalArgumentException` - if `end` happens before `start`
      `IOException` - if a stream can't be opened
    See Also:
      - `setToDisk(boolean)`

  - ### getDuration

    public Duration getDuration()
    Returns the specified duration for this recording, or `null` if no duration is set.

    The duration can be set only when the recording is in the `RecordingState.NEW` state.

    Returns:
      the desired duration of the recording, or `null` if no duration has been set.

  - ### setDuration

    public void setDuration(Duration duration)
    Sets a duration for how long a recording runs before it stops.

    By default, a recording has no duration (`null`).

    Parameters:
      `duration` - the duration, or `null` if no duration is set
    Throws:
      `IllegalStateException` - if recording is in the `STOPPED` or `CLOSED` state

  - ### enable

    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.

    Parameters:
      `name` - the settings for the event, not `null`
    Returns:
      an event setting for further configuration, not `null`
    See Also:
      - `EventType`

  - ### disable

    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 is disabled. To disable a specific class, use the `disable(Class)` method or a `String` representation of the event type ID.

    Parameters:
      `name` - the settings for the event, not `null`
    Returns:
      an event setting for further configuration, not `null`

  - ### enable

    public EventSettings enable(Class<? extends Event> eventClass)
    Enables event.
    Parameters:
      `eventClass` - the event to enable, not `null`
    Returns:
      an event setting for further configuration, not `null`
    Throws:
      `IllegalArgumentException` - if `eventClass` is an abstract class or not a subclass of `Event`

  - ### disable

    public EventSettings disable(Class<? extends Event> eventClass)
    Disables event.
    Parameters:
      `eventClass` - the event to enable, not `null`
    Returns:
      an event setting for further configuration, not `null`
    Throws:
      `IllegalArgumentException` - if `eventClass` is an abstract class or not a subclass of `Event`