Пакет jdk.jfr

Этот пакет предоставляет классы для создания событий и управления Flight Recorder.

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

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

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

Имя	Описание	Значение по умолчанию	Формат	Примеры значений
enabled	Указывает, записывается ли событие	"true"	Строковое представление Boolean ("true" или "false")	"true" "false"
threshold	Указывает продолжительность, ниже которой событие не записывается	"0" (нет ограничения)	"0" если порог не используется, иначе строковое представление положительного Long, за которым следует пробел и одна из следующих единиц: "ns" (наносекунды) "us" (микросекунды) "ms" (миллисекунды) "s" (секунды) "m" (минуты) "h" (часы) "d" (дни)	"0" "10 ms" "1 с"
period	Указывает интервал, с которым генерируется событие, если оно периодическое	"everyChunk"	"everyChunk", если периодическое событие должно генерироваться при каждой смене файла, иначе строковое представление положительного значения Long, за которым следует пробел и одна из следующих единиц: "ns" (наносекунды) "us" (микросекунды) "ms" (миллисекунды) "s" (секунды) "m" (минуты) "h" (часы) "d" (дни)	"20 ms" "1 s" "everyChunk"
stackTrace	Указывает, записывается ли стек вызовов из метода Event#commit()	"true"	Строковое представление Boolean ("true" или "false")	"true", "false"

Обработка null

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