Интерфейс EventStream

Поток — это последовательность событий, а способ взаимодействия с потоком — регистрация действий. Интерфейс EventStream не следует реализовывать, и будущие версии JDK могут вообще запретить это.

Для получения уведомления при поступлении события зарегистрируйте действие, используя метод onEvent(Consumer). Для фильтрации потока по событию с определенным именем используйте метод onEvent(String, Consumer).

По умолчанию один и тот же объект RecordedEvent может использоваться для представления двух или более различных событий. Этот объект может быть доставлен несколько раз одному и тому же действию, а также другим действиям. Чтобы использовать объект события после завершения действия, метод setReuse(boolean) должен быть установлен в значение false, чтобы для каждого события выделялся новый объект.

События доставляются партиями. Для получения уведомления о завершении пакетной обработки зарегистрируйте действие, используя метод onFlush(Runnable). Это возможность агрегировать или отправлять данные во внешние системы, пока виртуальная машина Java (JVM) готовит следующую партию.

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

Для отправки событий зарегистрированным действиям поток должен быть запущен. Для запуска обработки в текущей нити вызовите метод start(). Для асинхронной обработки действий в отдельной нити вызовите метод startAsync(). Для ожидания завершения потока используйте метод ожидания завершения awaitTermination() или awaitTermination(Duration).

Когда поток завершается, он автоматически закрывается. Чтобы вручную остановить обработку событий, закройте поток, вызвав метод close(). Поток также может быть автоматически закрыт в исключительных обстоятельствах, например, если выходит из строя отслеживаемая JVM. Для получения уведомления в любом из этих случаев используйте метод onClose(Runnable) для регистрации действия.

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

Следующий пример демонстрирует, как использовать EventStream для прослушивания событий в работающей JVM с Flight Recorder

try (var es = EventStream.openRepository()) {
    es.onEvent("jdk.CPULoad", event -> {
        System.out.println("CPU Load " + event.getEndTime());
        System.out.println(" Machine total: " + 100 * event.getFloat("machineTotal") + "%");
        System.out.println(" JVM User: " + 100 * event.getFloat("jvmUser") + "%");
        System.out.println(" JVM System: " + 100 * event.getFloat("jvmSystem") + "%");
        System.out.println();
    });
    es.onEvent("jdk.GarbageCollection", event -> {
        System.out.println("Garbage collection: " + event.getLong("gcId"));
        System.out.println(" Cause: " + event.getString("cause"));
        System.out.println(" Total pause: " + event.getDuration("sumOfPauses"));
        System.out.println(" Longest pause: " + event.getDuration("longestPause"));
        System.out.println();
    });
    es.start();
}

Чтобы начать запись вместе с потоком, см. RecordingStream.