Пакет jdk.jfr

Определение событий

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

Чтобы определить событие Flight Recorder, расширьте Event и добавьте поля, соответствующие типам данных полезной нагрузки. Метаданные полей, например метки, описания и единицы измерения, можно добавить с помощью аннотаций, доступных в пакете jdk.jfr, или с помощью пользовательской аннотации с аннотацией MetadataDefinition.

После определения класса события можно создавать его экземпляры (объекты событий). Данные сохраняются в событии путем присваивания значений полям. Время события можно явно контролировать с помощью методов begin и end, доступных в классе Event.

Сбор данных для сохранения в событии может быть затратным. Метод Event.shouldCommit() можно использовать, чтобы проверить, будет ли экземпляр события действительно записан в систему при вызове метода Event.commit(). Если Event.shouldCommit() возвращает false, эти операции можно пропустить.

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

Чтобы динамически определить событие, используйте класс EventFactory, определите поля с помощью класса ValueDescriptor и определите аннотации с помощью класса AnnotationElement. Используйте фабрику для создания события и метод Event.set(int, Object) для заполнения его данными.

Управление Flight Recorder

Flight Recorder можно контролировать локально с помощью средства командной строки jcmd или удаленно с помощью интерфейса FlightRecorderMXBean, зарегистрированного в платформенном MBeanServer. Если требуется прямой программный доступ, экземпляр Flight Recorder можно получить, вызвав FlightRecorder.getFlightRecorder(), а запись создать с помощью класса Recording, в котором настраивается объем записываемых данных.

Параметры и конфигурация

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

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

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

или

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

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

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

Предопределенные параметры

filter ::= target (";" target)*
target ::= class | class-method | method | annotation
class ::= identifier ("." identifier)*
class-method ::= class method
method ::= "::" method-name
method-name ::= identifier | "<clinit>" | "<init>"
annotation ::= "@" class
identifier ::= see JLS 3.8

Обработка null

В Javadoc для всех методов указано, принимают ли они null или возвращают его. Обычно это выражается как "not null". Если параметру null присвоено значение в месте, где это не допускается, выбрасывается исключение java.lang.NullPointerException. Если методу, который выбрасывает другие исключения, например java.io.IOException, передан параметр null, приоритет имеет исключение java.lang.NullPointerException, если только в Javadoc метода явно не указано, как обрабатывается null, то есть путем выбрасывания исключения java.lang.IllegalArgumentException.