RecordingStream (Java SE 14 & JDK 14)
Description: declaration: module: jdk.jfr, package: jdk.jfr.consumer, class: RecordingStream
Keywords: jdk.jfr.consumer.RecordingStream class

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 Summary

  Constructors
  Constructor | Description
  --- | ---
  `RecordingStream()` | Creates an event stream for the current JVM (Java Virtual Machine).
  `RecordingStream​(Configuration configuration)` | Creates a recording stream using settings from a configuration.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `EventSettings` | `disable​(Class<? extends Event> eventClass)` | Disables event.
  `EventSettings` | `disable​(String name)` | Disables event with the specified name.
  `EventSettings` | `enable​(Class<? extends Event> eventClass)` | Enables event.
  `EventSettings` | `enable​(String name)` | Enables the event with the specified name.
  `void` | `setMaxAge​(Duration maxAge)` | Determines how far back data is kept for the stream.
  `void` | `setMaxSize​(long maxSize)` | Determines how much data is kept for the stream.
  `void` | `setSettings​(Map<String,​String> settings)` | Replaces all settings for this recording stream.

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

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

  ### Methods declared in interface jdk.jfr.consumer.EventStream

  `awaitTermination, awaitTermination, close, onClose, onError, onEvent, onEvent, onFlush, remove, setEndTime, setOrdered, setReuse, setStartTime, start, startAsync`

- ## 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