Класс Recording

java.lang.Object

jdk.jfr.Recording

Все реализованные интерфейсы:: Closeable, AutoCloseable

public final class Recording extends Object implements Closeable

Предоставляет средства для конфигурирования, запуска, остановки и сохранения данных записи на диск.

Следующий пример демонстрирует, как конфигурировать, запускать, останавливать и сохранять данные записи на диск.

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"));
}

С:: 9

Краткое описание конструкторов

Конструктор	Описание
`Recording()`	Создаёт запись без настроек.
`Recording(Map<String,String> settings)`	Создаёт запись с настройками из карты пар имя-значение.
`Recording(Configuration configuration)`	Создаёт запись с настройками из конфигурации.

Краткое описание методов

Модификатор и тип	Метод	Описание
`void`	`close()`	Освобождает все данные, связанные с этой записью.
`Recording`	`copy(boolean stop)`	Возвращает клон этой записи с новым идентификатором и именем записи.
`EventSettings`	`disable(Class<? extends Event> eventClass)`	Отключает событие.
`EventSettings`	`disable(String name)`	Отключает событие с указанным именем.
`void`	`dump(Path destination)`	Записывает данные записи в файл.
`EventSettings`	`enable(Class<? extends Event> eventClass)`	Включает событие.
`EventSettings`	`enable(String name)`	Включает событие с указанным именем.
`Path`	`getDestination()`	Возвращает целевой файл, в который записываются данные записи при остановке записи, или `null`, если целевой файл не задан.
`boolean`	`getDumpOnExit()`	Возвращает значение, указывающее, сохраняется ли эта запись на диск при завершении JVM.
`Duration`	`getDuration()`	Возвращает заданную длительность для этой записи или `null`, если длительность не задана.
`long`	`getId()`	Возвращает уникальный идентификатор этой записи.
`Duration`	`getMaxAge()`	Возвращает длительность хранения данных в репозитории на диске перед удалением.
`long`	`getMaxSize()`	Возвращает максимальный размер в байтах, после которого данные больше не хранятся в репозитории на диске.
`String`	`getName()`	Возвращает имя этой записи.
`Map<String,String>`	`getSettings()`	Возвращает настройки, используемые этой записью.
`long`	`getSize()`	Возвращает текущий размер этой записи в репозитории на диске в байтах.
`Instant`	`getStartTime()`	Возвращает время начала этой записи.
`RecordingState`	`getState()`	Возвращает текущее состояние записи.
`Instant`	`getStopTime()`	Возвращает время остановки этой записи.
`InputStream`	`getStream(Instant start, Instant end)`	Создаёт поток данных для указанного интервала.
`boolean`	`isToDisk()`	Возвращает `true`, если эта запись использует репозиторий на диске, `false` в противном случае.
`void`	`scheduleStart(Duration delay)`	Запускает эту запись с задержкой.
`void`	`setDestination(Path destination)`	Устанавливает местоположение, в которое записываются данные при остановке записи, или `null`, если данные не должны сохраняться.
`void`	`setDumpOnExit(boolean dumpOnExit)`	Устанавливает, сохраняется ли эта запись на диск при завершении JVM.
`void`	`setDuration(Duration duration)`	Устанавливает длительность работы записи перед её остановкой.
`void`	`setMaxAge(Duration maxAge)`	Определяет, как долго хранятся данные в репозитории на диске.
`void`	`setMaxSize(long maxSize)`	Определяет, сколько данных хранится в репозитории на диске.
`void`	`setName(String name)`	Устанавливает удобочитаемое имя (например, `"My Recording"`).
`void`	`setSettings(Map<String,String> settings)`	Заменяет все настройки этой записи.
`void`	`setToDisk(boolean disk)`	Определяет, непрерывно ли эта запись флушится в репозиторий на диске или данные ограничены доступными буферами в памяти.
`void`	`start()`	Запускает эту запись.
`boolean`	`stop()`	Останавливает эту запись.

Методы, объявленные в классе java.lang.Object

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

Подробное описание конструкторов

Запись

public Recording(Map<String,String> settings)

Создает запись с настройками из карты пар имя-значение.

Новое созданное состояние записи находится в состоянии RecordingState.NEW. Чтобы начать запись, вызовите метод start().

Параметры:

settings - настройки в виде карты пар имя-значение, не null

Исключения:

IllegalStateException - если Запись полётов не может быть создана (например, если в Java Virtual Machine (JVM) нет поддержки Записи полётов или если репозиторий файлов не может быть создан или доступен)

С тех пор:

См. также:

Запись

public Recording()

Создаёт запись без каких-либо настроек.

Исключения:: IllegalStateException - если Запись полётов не может быть создана (например, если в Java Virtual Machine (JVM) нет поддержки Записи полётов или если репозиторий файлов не может быть создан или доступен)

Запись

public Recording(Configuration configuration)

Создает запись с настройками из конфигурации.

Следующий пример демонстрирует, как создать запись, использующую предопределенную конфигурацию.

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

Новая созданная запись находится в состоянии RecordingState.NEW. Для запуска записи вызовите метод start().

Параметры:

configuration - конфигурация, содержащая настройки, которые нужно использовать, не null

Исключения:

См. также:

Подробное описание методов

start

public void start()

Запускает эту запись.

Рекомендуется настроить параметры записи и параметры событий перед вызовом этого метода. Преимущества этого подхода — более согласованное состояние при анализе записанных данных и улучшенная производительность, так как конфигурация может применяться атомарно.

После успешного вызова этого метода эта запись находится в состоянии RUNNING.

Исключения:: IllegalStateException - если запись уже запущена или находится в состоянии CLOSED

scheduleStart

public void scheduleStart(Duration delay)

Запускает эту запись с задержкой.

После успешного вызова этого метода эта запись находится в состоянии DELAYED.

Параметры:: delay - время ожидания перед запуском этой записи, не null
Исключения:: IllegalStateException - если запись не находится в состоянии NEW

stop

public boolean stop()

Останавливает эту запись.

После остановки запись нельзя запустить снова. Если у этой записи есть назначение, данные записываются в это назначение, а запись закрывается. После закрытия записи данные больше недоступны.

После успешного вызова этого метода эта запись будет находиться в состоянии STOPPED.

Возвращает:

true, если запись остановлена, false в противном случае

Исключения:

IllegalStateException - если запись не запущена или уже остановлена

См. также:

getSettings

public Map<String,String> getSettings()

Возвращает настройки, используемые этой записью.

Изменение возвращаемых Map не повлияет на настройки этой записи.

Если для этой записи не заданы настройки, возвращается пустая Map.

Возвращает:: настройки записи, не null

getSize

public long getSize()

Возвращает текущий размер этой записи в репозитории на диске, измеренный в байтах.

Размер обновляется при сбросе буферов записи. Если запись не записывается в репозиторий на диске, возвращаемый размер всегда 0.

Возвращает:: объем записанных данных, измеренный в байтах, или 0, если запись не записывается в репозиторий на диске

getStopTime

public Instant getStopTime()

Возвращает время остановки этой записи.

Возвращает:: время или null, если эта запись не остановлена

getStartTime

public Instant getStartTime()

Возвращает время начала этой записи.

Возвращает:: время или null, если эта запись не запущена

getMaxSize

public long getMaxSize()

Возвращает максимальный размер, измеренный в байтах, по достижении которого данные больше не хранятся в репозитории на диске.

Возвращает:: максимальный размер в байтах или 0, если максимальный размер не задан

getMaxAge

public Duration getMaxAge()

Возвращает длительность времени, в течение которого данные хранятся в репозитории на диске, прежде чем будут удалены.

Возвращает:: максимальная длительность времени или null, если максимальная длительность времени не установлена

getName

public String getName()

Возвращает имя этой записи.

По умолчанию имя совпадает с идентификатором записи.

Возвращает:: имя записи, не null

setSettings

public void setSettings(Map<String,String> settings)

Заменяет все настройки для этой записи.

Следующий пример показывает, как настроить параметры событий для записи.

    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);

Следующий пример показывает, как объединить настройки.

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

Параметры:: settings - устанавливаемые настройки, не null

getState

public RecordingState getState()

Возвращает состояние записи, в котором находится данная запись.

Возвращает:

состояние записи, не null

См. также:

close

public void close()

Освобождает все данные, связанные с этой записью.

После успешного вызова этого метода эта запись находится в состоянии CLOSED.

Определяет:: close в интерфейсе AutoCloseable
Определяет:: close в интерфейсе Closeable

copy

public Recording copy(boolean stop)

Возвращает копию этой записи с новым идентификатором и именем записи.

Копии полезны для выгрузки данных без остановки записи. После создания копии объем копируемых данных ограничен методом setMaxAge(Duration) и методом setMaxSize(long).

Параметры:: stop - true, если новая созданная копия должна быть остановлена немедленно, false в противном случае
Возвращает:: копию записи, не null

dump

public void dump(Path destination) throws IOException

Записывает данные записи в файл.

Для успешной выгрузки запись должна быть либо 1) запущенной, либо 2) остановленной и сохранённой на диске. Если запись находится в другом состоянии, выбрасывается IOException.

Параметры:

destination - местоположение, в которое записываются данные записи, не null

Исключения:

IOException - если данные записи не могут быть скопированы в указанное местоположение, например, если запись закрыта или путь к назначению недоступен для записи

См. также:

isToDisk

public boolean isToDisk()

Возвращает true, если это запись использует репозиторий диска, false в противном случае.

Если значение не задано, true возвращается.

Возвращает:: true, если запись использует репозиторий диска, false в противном случае

setMaxSize

public void setMaxSize(long maxSize)

Определяет, сколько данных сохраняется в репозитории диска.

Для управления объёмом данных записи, хранящихся на диске, можно указать максимальный объём сохраняемых данных. Когда предельное значение превышено, Java Virtual Machine (JVM) удаляет самый старый фрагмент, чтобы освободить место для более нового фрагмента.

Если не установлен ни максимальный лимит, ни максимальный срок хранения, размер записи может неограниченно расти.

Параметры:: maxSize - количество данных для хранения, 0 если бесконечно
Исключения:: IllegalArgumentException - если maxSize отрицательно; IllegalStateException - если запись находится в состоянии CLOSED

setMaxAge

public void setMaxAge(Duration maxAge)

Определяет, как долго данные хранятся в репозитории диска.

Для управления объёмом данных записи, хранящихся на диске, можно указать максимальное время хранения данных. Данные, хранящиеся на диске, которые старше указанного периода времени, удаляются Java Virtual Machine (JVM).

Параметры:: maxAge - продолжительность хранения данных или null если бесконечно
Исключения:: IllegalArgumentException - если maxAge отрицательно; IllegalStateException - если запись находится в состоянии CLOSED

setDestination

public void setDestination(Path destination) throws IOException

Устанавливает место, куда данные записываются при остановке записи, или null если данные не должны быть сохранены.

Если место назначения задано, эта запись автоматически закрывается после успешного копирования данных в путь назначения.

Если место назначения не задано, Flight Recorder сохраняет данные записи до тех пор, пока эта запись не будет закрыта. Используйте метод dump(Path) для ручного записи данных в файл.

Параметры:: destination - путь к месту назначения или null если запись не должна быть сохранена при остановке
Исключения:: IllegalStateException - если запись находится в состоянии STOPPED или CLOSED.; IOException - если путь недоступен для записи

getDestination

public Path getDestination()

Возвращает файл назначения, куда записываются данные записи при остановке, или null если место назначения не установлено.

Возвращает:: файл назначения или null если не задан.

getId

public long getId()

Возвращает уникальный идентификатор для этой записи.

Возвращает:: идентификатор записи

setName

public void setName(String name)

Устанавливает удобочитаемое имя (например, "My Recording").

Параметры:: name - имя записи, не null
Исключения:: IllegalStateException - если запись находится в состоянии CLOSED

setDumpOnExit

public void setDumpOnExit(boolean dumpOnExit)

Устанавливает, будет ли эта запись сохранена на диске при выходе JVM.

Параметры:: dumpOnExit - нужно ли сохранять эту запись при выходе JVM

getDumpOnExit

public boolean getDumpOnExit()

Возвращает, будет ли эта запись сохранена на диске при выходе JVM.

Если сохранение при выходе не установлено, false возвращается.

Возвращает:: true, если запись сохраняется при выходе, false в противном случае.

setToDisk

public void setToDisk(boolean disk)

Определяет, будет ли эта запись непрерывно сохраняться в репозитории диска или данные ограничатся доступными буферами памяти.

Параметры:: disk - true, если эта запись записывается на диск, false если в памяти

getStream

public InputStream getStream(Instant start, Instant end) throws IOException

Создает поток данных для указанного интервала.

Поток может содержать некоторые данные за пределами указанного диапазона.

Если запись не на диске, поток не может быть создан и null возвращается.

Параметры:

start - начальное время для потока или null для получения данных с начала записи

end - конечное время для потока или null для получения данных до текущего времени.

Возвращает:

входной поток или null если данные недоступны в интервале или запись не была записана на диск

Исключения:

IllegalArgumentException - если end происходит до start

IOException - если поток не может быть открыт

См. также:

getDuration

public Duration getDuration()

Возвращает заданную продолжительность для этой записи или null если продолжительность не задана.

Продолжительность может быть установлена только когда запись находится в состоянии RecordingState.NEW.

Возвращает:: желаемую продолжительность записи или null если продолжительность не задана.

setDuration

public void setDuration(Duration duration)

Устанавливает продолжительность записи, после которой она останавливается.

По умолчанию у записи нет продолжительности (null).

Параметры:: duration - продолжительность или null если продолжительность не задана
Исключения:: IllegalStateException - если запись находится в состоянии STOPPED или CLOSED

enable

public EventSettings enable(String name)

Включает событие с указанным именем.

Если несколько событий имеют одинаковое имя (например, один и тот же класс загружен в разных загрузчиках классов), то все события, соответствующие имени, включены. Чтобы включить определённый класс, используйте метод enable(Class) или String представление идентификатора типа события.

Параметры:

name - настройки события, не null

Возвращает:

настройки события для дальнейшей настройки, не null

См. также:

disable

public EventSettings disable(String name)

Отключает событие с указанным именем.

Если несколько событий с одинаковым именем (например, один и тот же класс загружен в разных загрузчиках классов), то все события, соответствующие имени, отключаются. Чтобы отключить определенный класс, используйте метод disable(Class) или String представление идентификатора типа события.

Параметры:: name - настройки события, не null
Возвращает:: настройки события для дальнейшей настройки, не null

enable

public EventSettings enable(Class<? extends Event> eventClass)

Включает событие.

Параметры:: eventClass - событие для включения, не null
Возвращает:: настройки события для дальнейшей настройки, не null
Исключения:: IllegalArgumentException - если eventClass является абстрактным классом или не является подклассом Event

disable

public EventSettings disable(Class<? extends Event> eventClass)

Отключает событие.

Параметры:: eventClass - событие для отключения, не null
Возвращает:: настройки события для дальнейшей настройки, не null
Исключения:: IllegalArgumentException - если eventClass является абстрактным классом или не является подклассом Event

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/jdk.jfr/jdk/jfr/Recording.html