Интерфейс 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\recording.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()`	Создает снимок записи со всеми доступными записанными данными.

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

getObjectName

Модификатор и тип	Метод	Описание
`ObjectName`	`getObjectName()`	Возвращает экземпляр `ObjectName`, представляющий имя объекта этого управляемого объекта платформы.

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

MXBEAN_NAME

static final String MXBEAN_NAME

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

См. также:

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

newRecording

long newRecording() throws IllegalStateException

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

Возвращает:

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

Вызывает исключение:

IllegalStateException — если невозможно создать Flight Recorder (например, если виртуальная машина Java (JVM) не поддерживает Flight Recorder или если невозможно создать репозиторий файлов либо получить к нему доступ)

См. также:

takeSnapshot

long takeSnapshot()

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

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

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

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

Возвращает:

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

См. также:

cloneRecording

long cloneRecording(long recordingId, boolean stop) throws IllegalArgumentException

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

Клонированная запись содержит те же записанные данные, что и исходная, но имеет новый идентификатор и имя с префиксом "Clone of recording". Если исходная запись выполняется, клонированная запись также выполняется.

Параметры:

recordingId — идентификатор записи, из которой нужно создать клон

stop — следует ли остановить только что созданный клон перед возвратом.

Возвращает:

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

Вызывает исключение:

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

См. также:

startRecording

void startRecording(long recordingId) throws IllegalStateException

Запускает запись с указанным идентификатором.

Остановленную запись нельзя запустить повторно.

Параметры:

recordingId — идентификатор записи, которую нужно запустить

Вызывает исключение:

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

IllegalStateException

См. также:

stopRecording

boolean stopRecording(long recordingId) throws IllegalArgumentException, IllegalStateException

Останавливает выполняющуюся запись с указанным идентификатором.

Параметры:

recordingId — идентификатор записи, которую нужно остановить

Возвращает:

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

Вызывает исключение:

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

IllegalStateException — если запись не выполняется

См. также:

closeRecording

void closeRecording(long recordingId) throws IOException

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

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

Параметры:

recordingId — идентификатор записи, которую нужно закрыть

Вызывает исключение:

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

IOException — если возникает ошибка ввода-вывода

См. также:

openStream

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

Открывает поток данных для записи с указанным идентификатором или 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"`	Положительное значение `long`. Установка для `blockSize` очень большого значения может привести к `OutOfMemoryError` или `IllegalArgumentException`, если виртуальная машина Java (JVM) сочтет это значение слишком большим для обработки.	`"50000"`, `"1000000"`,
`streamVersion`	Задает формат для чтения данных из выполняющейся записи	`"1.0"`	Номер версии, состоящий из основной и дополнительной частей. Чтобы иметь возможность читать данные из выполняющейся записи, необходимо задать значение	`"1.0"`

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

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

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

closeStream

void closeStream(long streamId) throws IOException

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

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

Параметры:

streamId — идентификатор потока

Вызывает исключение:

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

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

См. также:

readStream

byte[] readStream(long streamId) throws IOException

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

Чтобы прочитать все данные записи, вызывайте этот метод повторно, пока он не вернет null.

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

getRecordingOptions

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

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

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

Параметры:: recordingId — идентификатор записи, параметры которой нужно получить
Возвращает:: карта с описанием параметров записи, не null
Вызывает исключение:: IllegalArgumentException — если запись с указанным идентификатором не существует

getRecordingSettings

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

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

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

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

Параметры:: recordingId — идентификатор записи, настройки которой нужно получить
Возвращает:: карта с описанием настроек записи, не null
Вызывает исключение:: IllegalArgumentException — если запись с указанным идентификатором не существует

setConfiguration

void setConfiguration(long recordingId, String contents) throws IllegalArgumentException

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

Параметры:

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

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

Вызывает исключение:

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

См. также:

setPredefinedConfiguration

void setPredefinedConfiguration(long recordingId, String configurationName) throws IllegalArgumentException

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

Параметры:

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

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

Вызывает исключение:

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

См. также:

setRecordingSettings

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

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

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

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

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

или

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

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

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

Параметры:

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

settings — карта пар «имя/значение» задаваемых настроек; не null

Вызывает исключение:

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

См. также:

setRecordingOptions

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

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

Описание доступных параметров и значений см. в разделе FlightRecorderMXBean. Чтобы восстановить значение по умолчанию, задайте null.

Параметры:

recordingId — идентификатор записи, параметры которой нужно задать

options — карта пар «имя/значение» задаваемых параметров; не null

Вызывает исключение:

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

См. также:

getRecordings

List<RecordingInfo> getRecordings()

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

Доступ через MBeanServer:
Отображаемый тип RecordingInfo — CompositeData с атрибутами, указанными в методе RecordingInfo.from.

Возвращает:

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

См. также:

getConfigurations

List<ConfigurationInfo> getConfigurations()

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

Доступ через MBeanServer:
Отображаемый тип ConfigurationInfo — CompositeData с атрибутами, указанными в методе ConfigurationInfo.from.

Возвращает:

список предварительно определенных конфигураций; не null

См. также:

getEventTypes

List<EventTypeInfo> getEventTypes()

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

Доступ через MBeanServer:
Отображаемый тип EventTypeInfo — CompositeData с атрибутами, указанными в методе EventTypeInfo.from.

Возвращает:

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

См. также:

copyTo

void copyTo(long recordingId, String outputFile) throws IOException

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

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

Параметры:

recordingId — идентификатор записи, данные которой нужно выгрузить

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

Вызывает исключение:

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

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

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

См. также:

© 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.