Интерфейс 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 Virtual Machine (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 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 Virtual Machine (JVM).
List<EventTypeInfo> getEventTypes()

Возвращает список текущих зарегистрированных типов событий.
Map<String,​String> getRecordingOptions​(long recordingId)

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

Возвращает список доступных записей, не обязательно выполняющихся.
Map<String,​String> getRecordingSettings​(long recordingId)

Возвращает Map, содержащий настройки записи с указанным ID (например, пороги событий).
long newRecording()

Создает запись, но не запускает её.
long openStream​(long recordingId, Map<String,​String> streamOptions)

Открывает поток данных для записи с указанным идентификатором или 0 для получения данных независимо от записи.
byte[] readStream​(long streamId)

Считывает часть данных из потока с указанным ID или возвращает null если больше данных недоступно.
void setConfiguration​(long recordingId, String contents)

Устанавливает конфигурацию в виде строкового представления для записи с указанным ID.
void setPredefinedConfiguration​(long recordingId, String configurationName)

Устанавливает предварительно определенную конфигурацию для записи с указанным ID.
void setRecordingOptions​(long recordingId, Map<String,​String> options)

Настраивает параметры записи (например, целевой файл и временной интервал для хранения данных).
void setRecordingSettings​(long recordingId, Map<String,​String> settings)

Устанавливает и заменяет все предыдущие настройки для указанной записи.
void startRecording​(long recordingId)

Запускает запись с указанным ID.
boolean stopRecording​(long recordingId)

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

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

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

getObjectName

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

MXBEAN_NAME

static final String MXBEAN_NAME

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

См. также:
Постоянные значения полей

Методы

newRecording

long newRecording()
           throws IllegalStateException,
                  SecurityException

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

Возвращает:
уникальный идентификатор, который может быть использован для запуска, остановки, закрытия и настройки записи
Выбрасывает:
IllegalStateException - если Flight Recorder не может быть создан (например, если в Java Virtual Machine (JVM) нет поддержки Flight Recorder, или если каталог для файлов не может быть создан или доступен)
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("control")
См. также:
Recording

takeSnapshot

long takeSnapshot()

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

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

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

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

Возвращает:
снимок всех доступных данных записи, не null
Выбрасывает:
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("control")
См. также:
Recording

cloneRecording

long cloneRecording(long recordingId,
                    boolean stop)
             throws IllegalArgumentException,
                    SecurityException

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

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

Параметры:
recordingId - идентификатор записи, для которой нужно создать копию
stop - если только что созданная копия должна быть остановлена перед возвратом.
Возвращает:
уникальный идентификатор, который может быть использован для запуска, остановки, закрытия и настройки записи
Выбрасывает:
IllegalArgumentException - если записи с указанным идентификатором не существует
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("control")
См. также:
Recording

startRecording

void startRecording(long recordingId)
             throws IllegalStateException,
                    SecurityException

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

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

Параметры:
recordingId - идентификатор записи, которую нужно запустить
Выбрасывает:
IllegalArgumentException - если записи с указанным идентификатором не существует
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("control")
IllegalStateException
См. также:
Recording

stopRecording

boolean stopRecording(long recordingId)
               throws IllegalArgumentException,
                      IllegalStateException,
                      SecurityException

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

Параметры:
recordingId - идентификатор записи, которую нужно остановить
Возвращает:
true если запись остановлена, false в противном случае
Выбрасывает:
IllegalArgumentException - если записи с указанным идентификатором не существует
IllegalStateException - если запись не запущена
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("control")
См. также:
newRecording()

closeRecording

void closeRecording(long recordingId)
             throws IOException

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

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

Параметры:
recordingId - идентификатор записи, которую нужно закрыть
Выбрасывает:
IllegalArgumentException - если записи с указанным идентификатором не существует
IOException - если произошла ошибка ввода-вывода
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("control")
См. также:
newRecording()

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 Virtual Machine (JVM) сочтёт это значение слишком большим.		 "50000",
"1000000",
Если параметр отсутствует в словаре, используется значение по умолчанию.

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

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

closeStream

void closeStream(long streamId)
          throws IOException

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

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

Параметры:
streamId - идентификатор потока
Выбрасывает:
IllegalArgumentException - если потока с указанным идентификатором не существует
IOException - если произошла ошибка ввода-вывода при попытке закрыть поток
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("control")
См. также:
openStream(long, Map)

readStream

byte[] readStream(long streamId)
           throws IOException

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

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

Параметры:
streamId - идентификатор потока
Возвращает:
массив байтов, содержащий данные записи, или null когда больше данных недоступно
Выбрасывает:
IOException - если поток закрыт или произошла ошибка ввода-вывода при попытке чтения потока
IllegalArgumentException - если записи с указанным идентификатором потока не существует
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("monitor")

getRecordingOptions

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

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

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

Параметры:
recordingId - идентификатор записи, для которой нужно получить параметры
Возвращает:
словарь, описывающий параметры записи, не null
Выбрасывает:
IllegalArgumentException - если записи с указанным идентификатором не существует
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("monitor")

getRecordingSettings

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

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

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

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

Параметры:
recordingId - идентификатор записи, для которой нужно получить настройки
Возвращает:
словарь, описывающий настройки записи, не null
Выбрасывает:
IllegalArgumentException - если записи с указанным идентификатором не существует
SecurityException - если существует менеджер безопасности и у вызывающего объекта нет ManagementPermission("monitor")

setConfiguration

void setConfiguration(long recordingId,
                      String contents)
               throws IllegalArgumentException

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

Параметры:
recordingId - Идентификатор записи
contents - строковое представление конфигурационного файла для использования, не null
Исключение:
IllegalArgumentException - если запись с указанным идентификатором не существует или конфигурация не может быть обработана.
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет ManagementPermission("control")
См. также:
Configuration.getContents()

setPredefinedConfiguration

void setPredefinedConfiguration(long recordingId,
                                String configurationName)
                         throws IllegalArgumentException

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

Параметры:
recordingId - Идентификатор записи, для которой нужно установить конфигурацию
configurationName - имя конфигурации (например, "profile" или "default"), не null
Исключение:
IllegalArgumentException - если запись с указанным идентификатором не существует
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет ManagementPermission("control")
См. также:
getConfigurations()

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().

Параметры:
recordingId - Идентификатор записи
settings - карта имя-значение настроек для установки, не null
Исключение:
IllegalArgumentException - если запись с указанным идентификатором не существует
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет ManagementPermission("control")
См. также:
Recording.getId()

setRecordingOptions

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

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

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

Параметры:
recordingId - идентификатор записи, для которой нужно установить параметры
options - карта имя/значение настроек для установки, не null
Исключение:
IllegalArgumentException - если запись с указанным идентификатором не существует
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет ManagementPermission("control") или параметр содержит файл, для доступа к которому у вызывающего объекта нет разрешения.
См. также:
Recording.getId()

getRecordings

List<RecordingInfo> getRecordings()

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

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

Возвращает:
список записей, не null
Исключение:
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет ManagementPermission("monitor")
См. также:
RecordingInfo, Recording

getConfigurations

List<ConfigurationInfo> getConfigurations()

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

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

Возвращает:
список предопределённых конфигураций, не null
Исключение:
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет ManagementPermission("monitor")
См. также:
ConfigurationInfo, Configuration

getEventTypes

List<EventTypeInfo> getEventTypes()

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

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

Возвращает:
список зарегистрированных типов событий, не null
Исключение:
SecurityException - если менеджер безопасности существует, и у вызывающего объекта нет ManagementPermission("monitor")
См. также:
EventTypeInfo, EventType

copyTo

void copyTo(long recordingId,
            String outputFile)
     throws IOException,
            SecurityException

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

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

Параметры:
recordingId - идентификатор записи, для которой нужно скопировать данные
outputFile - зависящее от системы имя файла, в который записываются данные, не null
Исключение:
IOException - если запись не может быть скопирована из-за ошибки ввода-вывода (например, некорректный путь)
IllegalArgumentException - если запись с указанным идентификатором не существует
IllegalStateException - если запись ещё не начата или уже закрыта
SecurityException - если менеджер безопасности существует и его метод SecurityManager.checkWrite(java.lang.String) запрещает запись в указанный файл или у вызывающего объекта нет ManagmentPermission("control")
См. также:
Path.toString(), Recording.dump(java.nio.file.Path)

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

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