Класс Запись

Все реализованные интерфейсы:
Closeable, AutoCloseable 
public final class Recording
extends Object
implements Closeable

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

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

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"));
С момента:
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)

Запись

public Recording()

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

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

Исключения:
IllegalStateException - если Flight Recorder не может быть создан (например, если в виртуальной машине Java (JVM) отсутствует поддержка Flight Recorder, или если хранилище файлов не может быть создано или обработано)
SecurityException - Если используется менеджер безопасности, а разрешение FlightRecorderPermission "accessFlightRecorder" не установлено.

Запись

public Recording(Configuration configuration)

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

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

Recording r = new Recording(Configuration.getConfiguration("default"));
Новая запись находится в состоянии RecordingState.NEW. Чтобы запустить запись, вызовите метод start().
Параметры:
configuration - конфигурация, содержащая настройки для использования, а не null
Исключения:
IllegalStateException - если Flight Recorder не может быть создан (например, если в виртуальной машине Java (JVM) отсутствует поддержка Flight Recorder, или если хранилище файлов не может быть создано или обработано)
SecurityException - если используется менеджер безопасности, а разрешение FlightRecorderPermission "accessFlightRecorder" не установлено.
См. также:
Configuration

Методы

start

public void start()

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

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

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

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

scheduleStart

public void scheduleStart(Duration delay)

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

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

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

stop

public boolean stop()

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

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

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

Returns:
true если запись остановлена, false в противном случае
Throws:
IllegalStateException - если запись не запущена или уже остановлена
SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет FilePermission для записи в путь назначения
See Also:
setDestination(Path)

getSettings

public Map<String,String> getSettings()

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

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

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

Returns:
настройки записи, не null

getSize

public long getSize()

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

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

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

getStopTime

public Instant getStopTime()

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

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

getStartTime

public Instant getStartTime()

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

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

getMaxSize

public long getMaxSize()

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

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

getMaxAge

public Duration getMaxAge()

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

Returns:
максимальная продолжительность времени, или null если максимальная продолжительность времени не была установлена

getName

public String getName()

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

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

Returns:
имя записи, не 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);
Parameters:
settings - настройки для установки, не null

getState

public RecordingState getState()

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

Returns:
состояние записи, не null
See Also:
RecordingState

close

public void close()

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

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

Specified by:
close в интерфейсе AutoCloseable
Specified by:
close в интерфейсе Closeable

copy

public Recording copy(boolean stop)

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

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

dump

public void dump(Path destination)
          throws IOException

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

Запись должна быть запущена, но не обязательно остановлена.

Parameters:
destination - местоположение, куда записываются данные записи, не null
Throws:
IOException - если запись не может быть скопирована в указанное местоположение
SecurityException - если существует менеджер безопасности, и у вызывающего объекта нет FilePermission для записи в путь назначения

isToDisk

public boolean isToDisk()

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

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

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

setMaxSize

public void setMaxSize(long maxSize)

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

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

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

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

setMaxAge

public void setMaxAge(Duration maxAge)

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

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

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

Parameters:
maxAge - продолжительность хранения данных, или null если бесконечен
Throws:
IllegalArgumentException - если maxAge отрицательное
IllegalStateException - если запись находится в состоянии CLOSED

setDestination

public void setDestination(Path destination)
                    throws IOException

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

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

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

Parameters:
destination - путь назначения, или null если запись не должна быть выгружена при остановке
Throws:
IllegalStateException - если запись находится в состоянии STOPPED или CLOSED.
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет FilePermission для чтения, записи и удаления файла destination
IOException - если путь недоступен для записи

getDestination

public Path getDestination()

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

Returns:
целевой файл, или null если не задан.

getId

public long getId()

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

Returns:
идентификатор записи

setName

public void setName(String name)

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

Parameters:
name - имя записи, не null
Throws:
IllegalStateException - если запись находится в состоянии CLOSED

setDumpOnExit

public void setDumpOnExit(boolean dumpOnExit)

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

Parameters:
dumpOnExit - если эта запись должна быть выгружена при выходе JVM

getDumpOnExit

public boolean getDumpOnExit()

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

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

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

setToDisk

public void setToDisk(boolean disk)

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

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

getStream

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

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

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

Параметры:
the - начальное время потока, или null для получения данных с момента начала записи
the - конечное время потока, или 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
См. также:
EventType

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, 2020, 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://docs.oracle.com/en/java/javase/11/docs/api/jdk.jfr/jdk/jfr/Recording.html

Spec-Zone .ru
спецификации, руководства, описания, API