Пакет 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().

Предопределённые настройки

Обработка значений null

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