Интерфейс FlightRecorderMXBean

Все суперинтерфейсы:: PlatformManagedObject

public interface FlightRecorderMXBean extends PlatformManagedObject

Интерфейс управления Flight Recorder.

Имя объекта для идентификации MXBean в сервере MBean платформы:

jdk.management.jfr:type=FlightRecorder

Flight Recorder можно настроить следующими способами:

Параметры записи
Укажите, как долго должна длиться запись, и куда и когда данные должны быть записаны.
Настройки
Укажите, какие события должны быть включены и какую информацию каждое событие должно собирать.
Конфигурации
Предварительно определённые наборы настроек, обычно полученные из файла настроек, которые задают конфигурацию нескольких событий одновременно.

См. документацию пакета jdk.jfr для описания синтаксиса настроек и документацию класса ConfigurationInfo для информации о конфигурации.

Параметры записи

В следующей таблице показаны имена параметров, используемые с setRecordingOptions(long, Map) и getRecordingOptions(long).

Параметры записи
Имя	Описание	Значение по умолчанию	Формат	Примеры значений
`name`	Устанавливает имя записи в удобочитаемом формате	Строковое представление идентификатора записи	`String`	`"My Recording"`, `"profiling"`
`maxAge`	Укажите длительность хранения данных в хранилище на диске, после чего самые старые данные могут быть удалены. Работает только если `disk=true`, в противном случае этот параметр игнорируется.	`"0"` (без ограничения)	`"0"` если ограничения нет, в противном случае строковое представление положительного `Long` значения, за которым следует пробел и одна из следующих единиц измерения `"ns"` (наносекунды) `"us"` (микросекунды) `"ms"` (миллисекунды) `"s"` (секунды) `"m"` (минуты) `"h"` (часы) `"d"` (дни)	`"2 h"`, `"24 h"`, `"2 d"`, `"0"`
`maxSize`	Указывает размер, измеренный в байтах, по достижении которого данные хранятся в хранилище на диске. Работает только если `disk=true`, в противном случае этот параметр игнорируется.	`"0"` (без ограничения)	Строковое представление `Long` значения, должно быть положительным	`"0"`, `"1000000000"`
`dumpOnExit`	Записывает данные записи на диск при выходе виртуальной машины Java (JVM)	`"false"`	Строковое представление `Boolean` значения, `"true"` или `"false"`	`"true"`, `"false"`
`destination`	Указывает путь, куда записываются данные записи при остановке записи.	`"false"`	См. `Paths#getPath` для формата. Если этот метод вызван из другого процесса, данные записываются на машину, на которой запущена целевая JVM. Если путь является относительным, он относительный к рабочему каталогу, где была запущена целевая JVM.	`"c:\recording\recotding.jfr"`, `"/recordings/recording.jfr"`, `"recording.jfr"`
`disk`	Хранит записанные данные так, как они записываются	`"false"`	Строковое представление `Boolean` значения, `"true"` или `"false"`	`"true"`, `"false"`
`duration`	Устанавливает, как долго должна работать запись	`"0"` (без ограничения, непрерывно)	`"0"` если ограничение не должно быть установлено, в противном случае строковое представление положительного `Long` значения, за которым следует пробел и одна из следующих единиц: `"ns"` (наносекунды) `"us"` (микросекунды) `"ms"` (миллисекунды) `"s"` (секунды) `"m"` (минуты) `"h"` (часы) `"d"` (дни)	`"60 s"`, `"10 m"`, `"4 h"`, `"0"`

С:: 9

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final String`	`MXBEAN_NAME`	Строковое представление `ObjectName` для `FlightRecorderMXBean`.

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

Модификатор и тип	Метод	Описание
`long`	`cloneRecording(long recordingId, boolean stop)`	Создает копию существующей записи, полезно для извлечения фрагментов записи.
`void`	`closeRecording(long recordingId)`	Закрывает запись с указанным идентификатором и освобождает все системные ресурсы, связанные с записью.
`void`	`closeStream(long streamId)`	Закрывает поток записи с указанным идентификатором и освобождает все системные ресурсы, связанные с потоком.
`void`	`copyTo(long recordingId, String outputFile)`	Записывает данные записи в указанный файл.
`List<ConfigurationInfo>`	`getConfigurations()`	Возвращает список предварительно определенных конфигураций для этой виртуальной машины Java (JVM).
`List<EventTypeInfo>`	`getEventTypes()`	Возвращает список текущих зарегистрированных типов событий.
`Map<String,String>`	`getRecordingOptions(long recordingId)`	Возвращает карту, содержащую параметры записи с указанным идентификатором (например, целевой файл или временной интервал хранения записанных данных).
`List<RecordingInfo>`	`getRecordings()`	Возвращает список доступных записей, не обязательно выполняющихся.
`Map<String,String>`	`getRecordingSettings(long recordingId)`	Возвращает `Map`, содержащую настройки записи с указанным идентификатором (например, пороги событий).
`long`	`newRecording()`	Создает запись, но не запускает ее.
`long`	`openStream(long recordingId, Map<String,String> streamOptions)`	Открывает поток данных для записи с указанным идентификатором или `0`, чтобы получить данные независимо от записи.
`byte[]`	`readStream(long streamId)`	Читает часть данных из потока с указанным идентификатором или возвращает `null`, если больше данных недоступно.
`void`	`setConfiguration(long recordingId, String contents)`	Устанавливает конфигурацию в виде строкового представления для записи с указанным идентификатором.
`void`	`setPredefinedConfiguration(long recordingId, String configurationName)`	Устанавливает предопределенную конфигурацию для записи с указанным идентификатором.
`void`	`setRecordingOptions(long recordingId, Map<String,String> options)`	Настраивает параметры записи (например, целевой файл и временной интервал хранения данных).
`void`	`setRecordingSettings(long recordingId, Map<String,String> settings)`	Устанавливает и заменяет все предыдущие настройки для указанной записи.
`void`	`startRecording(long recordingId)`	Запускает запись с указанным идентификатором.
`boolean`	`stopRecording(long recordingId)`	Останавливает выполняющуюся запись с указанным идентификатором.
`long`	`takeSnapshot()`	Создает моментальную запись всех доступных записанных данных.

Методы, объявленные в интерфейсе java.lang.management.PlatformManagedObject

getObjectName

Подробное описание полей

MXBEAN_NAME

static final String MXBEAN_NAME

Строковое представление ObjectName для FlightRecorderMXBean.

См. также:

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

newRecording

long newRecording() throws IllegalStateException

Создаёт запись, но не запускает её.

Возвращает:

уникальный идентификатор, который может быть использован для запуска, остановки, закрытия и настройки записи

Выбрасывает:

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

См. также:

takeSnapshot

long takeSnapshot()

Создаёт запись-снимок всех доступных записанных данных.

Снимок — это синтетическая запись в состоянии остановки. Если данных нет, возвращается запись размером 0.

Снимок обеспечивает стабильный доступ к данным для последующих операций (например, для изменения временного интервала или уменьшения размера данных).

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

Возвращает:

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

См. также:

cloneRecording

long cloneRecording(long recordingId, boolean stop) throws IllegalArgumentException

Создаёт копию существующей записи, полезной для извлечения частей записи.

Скопированная запись содержит те же данные, что и оригинальная, но имеет новый ID и имя, начинающееся с "Clone of recording". Если оригинальная запись запущена, то и копия запущена.

Параметры:

recordingId - идентификатор записи, с которой создавать копию

stop - если новая копия останавливается перед возвратом.

Возвращает:

Выбрасывает:

IllegalArgumentException - если запись с заданным ID не существует

См. также:

startRecording

void startRecording(long recordingId) throws IllegalStateException

Запускает запись с указанным ID.

Остановленная запись не может быть перезапущена.

Параметры:

recordingId - ID записи для запуска

Выбрасывает:

IllegalArgumentException - если запись с заданным ID не существует

IllegalStateException

См. также:

stopRecording

boolean stopRecording(long recordingId) throws IllegalArgumentException, IllegalStateException

Останавливает запущенную запись с указанным ID.

Параметры:

recordingId - ID записи для остановки

Возвращает:

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

Выбрасывает:

IllegalArgumentException - если запись с заданным ID не существует

IllegalStateException - если запись не запущена

См. также:

closeRecording

void closeRecording(long recordingId) throws IOException

Закрывает запись с указанным ID и освобождает системные ресурсы, связанные с записью.

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

Параметры:

recordingId - ID записи для закрытия

Выбрасывает:

IllegalArgumentException - если запись с заданным ID не существует

IOException - если произошла ошибка ввода/вывода

См. также:

openStream

long openStream(long recordingId, Map<String,String> streamOptions) throws IOException

Открывает поток данных для записи с указанным ID или 0 для получения данных независимо от записи.

Параметры потока записи
Имя	Описание	Значение по умолчанию	Формат	Примеры значений
`startTime`	Указывает момент времени для начала потока записи. Из-за способа хранения данных могут быть включены некоторые события, начавшиеся или закончившиеся до начала времени.	`Instant.MIN_VALUE.toString()`	ISO-8601. См. `Instant.toString()` или миллисекунды с эпохи	`"2015-11-03T00:00"`, `"1446508800000"`
`endTime`	Указывает момент времени для завершения потока записи. Из-за способа хранения данных могут быть включены некоторые события, начавшиеся или закончившиеся после времени окончания.	`Instant.MAX_VALUE.toString()`	ISO-8601. См. `Instant.toString()` или миллисекунды с эпохи	`"2015-11-03T01:00"`, `"1446512400000"`
`blockSize`	Указывает максимальное количество байтов для чтения с помощью вызова `readStream`	`"50000"`	Положительное целочисленное значение. Установка `blockSize` к очень большому значению может привести к `OutOfMemoryError` или `IllegalArgumentException`, если Java Virtual Machine (JVM) сочтёт это значение слишком большим для обработки.	`"50000"`, `"1000000"`,
`streamVersion`	Указывает формат для чтения данных из запущенной записи	`"1.0"`	Номер версии с мажорной и минорной частью. Чтобы читать из запущенной записи, это значение должно быть задано	`"1.0"`

Если опция опущена из карты, используется значение по умолчанию.

Запись с указанным ID должна быть остановлена перед открытием потока, если не указана опция "streamVersion".

Параметры:: recordingId - ID записи для открытия потока; streamOptions - карта, содержащая параметры, контролирующие количество данных и способ их чтения, или null для получения всех данных для записи с размерами по умолчанию
Возвращает:: уникальный ID для потока.
Выбрасывает:: IllegalArgumentException - если запись с ID не существует, или если options содержит некорректные значения; IOException - если запись закрыта, произошла ошибка ввода/вывода, или данные недоступны для указанной записи или интервала

closeStream

void closeStream(long streamId) throws IOException

Закрывает поток записи с указанным ID и освобождает системные ресурсы, связанные с потоком.

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

Параметры:

streamId - ID потока

Выбрасывает:

IllegalArgumentException - если поток с указанным ID не существует

IOException - если при закрытии потока произошла ошибка ввода/вывода

См. также:

readStream

byte[] readStream(long streamId) throws IOException

Читает часть данных из потока с указанным ID или возвращает null, если больше данных нет.

Для чтения всех данных записи вызывайте этот метод повторно до тех пор, пока не вернётся null.

Параметры:: streamId - ID потока
Возвращает:: массив байтов, содержащий данные записи, или null, когда больше данных нет
Выбрасывает:: IOException - если поток закрыт или произошла ошибка ввода/вывода при чтении из потока; IllegalArgumentException - если запись с указанным ID потока не существует

getRecordingOptions

Map<String,String> getRecordingOptions(long recordingId) throws IllegalArgumentException

Возвращает карту, содержащую параметры записи с указанным ID (например, целевой файл или временной интервал для хранения записанных данных).

См. FlightRecorderMXBean для доступных имён параметров.

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

getRecordingSettings

Map<String,String> getRecordingSettings(long recordingId) throws IllegalArgumentException

Возвращает Map, содержащую настройки записи с указанным идентификатором (например, пороговые значения событий).

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

Имя в Map представляет собой имя события и имя настройки, разделенные "#" (например, "jdk.VMInfo#period"). Значение — текстовое представление значения настройки (например, "60 s").

Parameters:: recordingId — идентификатор записи, для которой необходимо получить настройки
Returns:: карта, описывающая настройки записи, не null
Throws:: IllegalArgumentException — если запись с указанным идентификатором не существует

setConfiguration

void setConfiguration(long recordingId, String contents) throws IllegalArgumentException

Устанавливает конфигурацию в виде строкового представления для записи с указанным идентификатором.

Parameters:

recordingId — идентификатор записи

contents — строковое представление конфигурационного файла для использования, не null

Throws:

IllegalArgumentException — если запись с указанным идентификатором не существует или конфигурация не может быть обработана.

See Also:

setPredefinedConfiguration

void setPredefinedConfiguration(long recordingId, String configurationName) throws IllegalArgumentException

Устанавливает предопределенную конфигурацию для записи с указанным идентификатором.

Parameters:

recordingId — идентификатор записи, для которой необходимо установить конфигурацию

configurationName — имя конфигурации (например, "profile" или "default"), не null

Throws:

IllegalArgumentException — если запись с указанным идентификатором не существует

See Also:

setRecordingSettings

void setRecordingSettings(long recordingId, Map<String,String> settings) throws IllegalArgumentException

Устанавливает и заменяет все предыдущие настройки для указанной записи.

Настройка состоит из пары имя/значение, где имя указывает на событие и настройку для конфигурации, а значение — на то, на что нужно установить настройку.

Имя может быть сформировано следующим образом:

<event-name> + "#" + <setting-name>

или

<event-id> + "#" + <setting-name>

Например, для установки интервала дискретизации события CPU Load раз в секунду используйте имя "jdk.CPULoad#period" и значение "1 s". Если одно и то же имя используется для нескольких событий, например, если тип события загружается в нескольких загрузчиках классов, и требуется их различать, то имя имеет вид "56#period". Идентификатор события получается путем вызова метода EventType.getId() и является допустимым для экземпляра виртуальной машины Java (JVM), в котором зарегистрировано событие.

Список доступных имён событий можно получить, вызвав FlightRecorder.getEventTypes() и EventType.getName(). Список доступных настроек для типа события можно получить, вызвав EventType.getSettingDescriptors() и ValueDescriptor.getName().

Parameters:

recordingId — идентификатор записи

settings — карта имя-значение настроек, которые нужно установить, не null

Throws:

IllegalArgumentException — если запись с указанным идентификатором не существует

See Also:

setRecordingOptions

void setRecordingOptions(long recordingId, Map<String,String> options) throws IllegalArgumentException

Настраивает параметры записи (например, файл назначения и временной интервал хранения данных).

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

Parameters:

recordingId — идентификатор записи, для которой необходимо установить параметры

options — карта имя/значение настроек, которые нужно установить, не null

Throws:

IllegalArgumentException — если запись с указанным идентификатором не существует

See Also:

getRecordings

List<RecordingInfo> getRecordings()

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

Доступ к MBeanServer:
Картируемый тип для RecordingInfo — это CompositeData с атрибутами, как указано в методе RecordingInfo.from.

Returns:

список записей, не null

See Also:

getConfigurations

List<ConfigurationInfo> getConfigurations()

Возвращает список предопределенных конфигураций для данной виртуальной машины Java (JVM).

Доступ к MBeanServer:
Картируемый тип для ConfigurationInfo — это CompositeData с атрибутами, как указано в методе ConfigurationInfo.from.

Returns:

список предопределенных конфигураций, не null

See Also:

getEventTypes

List<EventTypeInfo> getEventTypes()

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

Доступ к MBeanServer:
Картируемый тип для EventTypeInfo — это CompositeData с атрибутами, как указано в методе EventTypeInfo.from.

Returns:

список зарегистрированных типов событий, не null

See Also:

copyTo

void copyTo(long recordingId, String outputFile) throws IOException

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

Если этот метод вызывается удалённо из другого процесса, данные записываются в файл с именем outputFile на компьютере, на котором запущена целевая виртуальная машина Java (JVM). Если путь к файлу — относительный, он относительный к рабочей директории, в которой была запущена целевая JVM.

Parameters:

recordingId — идентификатор записи, для которой необходимо скопировать данные

outputFile — имя файла, зависящее от системы, куда записываются данные, не null

Throws:

IOException — если запись не может быть скопирована из-за ошибки ввода-вывода (например, неверный путь)

IllegalArgumentException — если запись с указанным идентификатором не существует

IllegalStateException — если запись ещё не запущена или уже закрыта

See Also:

© 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.management.jfr/jdk/management/jfr/FlightRecorderMXBean.html