Module jdk.jfr
Package jdk.jfr.consumer

Class RecordingStream

java.lang.Object
jdk.jfr.consumer.RecordingStream
All Implemented Interfaces:
AutoCloseable, EventStream
public final class RecordingStream
extends Object
implements AutoCloseable, EventStream
A recording stream produces events from the current JVM (Java Virtual Machine).

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 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 have FlightRecorderPermission("accessFlightRecorder")

    • RecordingStream

      public RecordingStream​(Configuration configuration)
      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, 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

    • 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

    • setSettings

      public void setSettings​(Map<String,​String> settings)
      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, not null
      See Also:
      Recording.setSettings(Map)

    • 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​(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 are 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

    • 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

    • setMaxAge

      public void setMaxAge​(Duration maxAge)
      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, or null if infinite
      Throws:
      IllegalArgumentException - if maxAge is negative
      IllegalStateException - if the recording is in the CLOSED 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 - if maxSize is negative
      IllegalStateException - if the recording is in CLOSED state