Module jdk.jfr
Package jdk.jfr

Class 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.

    Example, 

     
   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

    • Constructor Summary

      Constructors 
      Constructor Description
      Recording()
      Creates a recording without any settings.
      Recording​(Configuration configuration)
      Creates a recording with settings from a configuration.

    • Constructor Detail

      • Recording

        public Recording()
        Creates a recording without any settings.

        A newly created recording will be in RecordingState.NEW. To start the recording invoke start().

        Throws:
        IllegalStateException - if the platform Flight Recorder couldn't be created, for instance if commercial features isn't unlocked, 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.

        Example, 

         
 Recording r = new Recording(Configuration.getConfiguration("default"));
        The newly created recording will be in RecordingState.NEW. To start the recording invoke start().
        Parameters:
        configuration - configuration containing settings to be used, not null
        Throws:
        IllegalStateException - if the platform Flight Recorder couldn't be created, for instance if commercial features isn't unlocked, 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 Detail

      • start

        public void start()
        Starts this recording.

        It's recommended that recording options and event settings are configured before calling this method, since it guarantees a more consistent state when analyzing the recorded data. It may also have performance benefits, since the configuration can be applied atomically.

        After a successful invocation of this method, the state of this recording will be in RUNNING state.

        Throws:
        IllegalStateException - if recording has already been started or is in CLOSED state

      • scheduleStart

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

        After a successful invocation of this method, the state of this recording will be in the DELAYED state.

        Parameters:
        delay - the time to wait before starting this recording, not null
        Throws:
        IllegalStateException - if already started or is in CLOSED state

      • stop

        public boolean stop()
        Stops this recording.

        Once a recording has been stopped it can't be restarted. If this recording has a destination, data will be written to that destination and the recording closed. Once a recording is closed, the data is no longer available.

        After a successful invocation of this method, the state of this recording will be in STOPPED state.

        Returns:
        true if recording was stopped, false otherwise
        Throws:
        IllegalStateException - if not started or already been stopped
        SecurityException - if a security manager exists and the caller doesn't have FilePermission to write at 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 settings for this recording.

        If no settings have been 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. Size is updated when recording buffers are flushed. If the recording is not to disk the returned is always 0.
        Returns:
        amount of recorded data, measured in bytes, or 0 if the recording is not to disk

      • getStopTime

        public Instant getStopTime()
        Returns the time when this recording was stopped.
        Returns:
        the the time, or null if this recording hasn't been stopped

      • getStartTime

        public Instant getStartTime()
        Returns the time when this recording was started.
        Returns:
        the the time, or null if this recording hasn't been started

      • getMaxSize

        public long getMaxSize()
        Returns the max size, measured in bytes, at which data will no longer be kept in the disk repository.
        Returns:
        max size in bytes, or 0 if no max size has been set

      • getMaxAge

        public Duration getMaxAge()
        Returns how long data is to be kept in the disk repository before it is thrown away.
        Returns:
        max age, or null if no maximum age 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:
        recording name, not null

      • setSettings

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

        Example, 

         
     Map<String, String> settings = new HashMap<>();
     settings.putAll(EventSettings.enabled("com.oracle.jdk.CPUSample").withPeriod(Duration.ofSeconds(2)).toMap());
     settings.putAll(EventSettings.enabled(MyEvent.class).withThreshold(Duration.ofSeconds(2)).withoutStackTrace().toMap());
     settings.put("com.oracle.jdk.ExecutionSample#period", "10 ms");
     recording.setSettings(settings);
        To merge with existing settings do. 
         
 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 RecordingState this recording is currently in.
        Returns:
        the recording state, not null
        See Also:
        RecordingState

      • close

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

        After a successful invocation of this method, the state of this recording will be 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, but 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 be copied out can be constrained with the setMaxAge(Duration) and setMaxSize(long).
        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.

        Recording must be started, but not necessarily stopped.

        Parameters:
        destination - where recording data should be written, not null
        Throws:
        IOException - if recording can't be copied to path
        SecurityException - if a security manager exists and the caller doesn't have FilePermission to write at the destination path

      • isToDisk

        public boolean isToDisk()
        Returns if this recording is to disk.

        If no value has been set, true is returned.

        Returns:
        true if recording is to disk, false otherwise

      • setMaxSize

        public void setMaxSize​(long maxSize)
        Determines how much data should be kept in disk repository.

        In order to control the amount of recording data stored on disk, and not having it grow indefinitely, Max size can be used to limit the amount of data retained. When the maxSize limit has been exceeded, the JVM will remove the oldest chunk to make room for a more recent chunk.

        Parameters:
        maxSize - or 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 should be kept in disk repository.

        In order to control the amount of recording data stored on disk, and not having it grow indefinitely, maxAge can be used to limit the amount of data retained. Data stored on disk which is older than maxAge will be removed by Flight Recorder.

        Parameters:
        maxAge - how long data can be kept, or null if infinite
        Throws:
        IllegalArgumentException - if maxAge is negative
        IllegalStateException - if the recording is in closed state

      • setDestination

        public void setDestination​(Path destination)
                    throws IOException
        Sets a location where data will be written on recording stop, or null if data should not be dumped automatically.

        If a destination is set, this recording will be closed automatically after data has been copied successfully to the destination path.

        If a destination is not set, Flight Recorder will hold on to recording data until this recording is closed. Use dump(Path) to write data to a file manually.

        Parameters:
        destination - destination path, or null if recording should not be dumped at stop
        Throws:
        IllegalStateException - if recording is in ETOPPED 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 path is not writable

      • getDestination

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

      • getId

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

      • setName

        public void setName​(String name)
        Sets a human-readable name, such as "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 if this recording should be dumped to disk when the JVM exits.
        Parameters:
        dumpOnExit - if recording should be dumped on JVM exit

      • getDumpOnExit

        public boolean getDumpOnExit()
        Returns if this recording should be dumped to disk when the JVM exits.

        If dump on exit has not been set, false is returned.

        Returns:
        true if recording should be dumped on exit, false otherwise.

      • setToDisk

        public void setToDisk​(boolean disk)
        Determines if this recording should be flushed to disk continuously or if data should be constrained to what is available in memory buffers.
        Parameters:
        disk - true if recording should be 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.
        Parameters:
        start - start time for the stream, or null to get data from start time of the recording
        end - 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.
        Throws:
        IllegalArgumentException - if end happens before start
        IOException - if a stream can't be opened

      • getDuration

        public Duration getDuration()
        Returns the desired duration for this recording, or null if no duration has been set.

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

        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 should run before it's stopped.

        By default a recording has no duration (null).

        Parameters:
        duration - the duration or null if no duration should be used
        Throws:
        IllegalStateException - if recording is in stopped or closed state

      • enable

        public EventSettings enable​(String name)
        Enables the event with the specified name.

        If there are multiple events with same name, which can be the case if the same class is loaded in different class loaders, all events matching the name will be 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 there are multiple events with same name, which can be the case if the same class is loaded in different class loaders, all events matching the name will be 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