JEP draft: Native Profiler Hook for Unbiased Stack Traces (Experimental)
Нативный хук профилировщика для получения трассировок стека без смещения (в статусе Experimental (экспериментальная функция))
| Authors | Roman Kennke, Ron Pressler |
| Ответственный | Roman Kennke |
| Тип | Feature |
| Область | JDK |
| Статус | Submitted |
| Компонент | hotspot / jvmti |
| Обсуждение | serviceability dash dev at openjdk dot org |
| Трудоёмкость | M |
| Рецензенты | Markus Grönlund, Serguei Spitsyn |
| Создан | 2026/03/17 12:49 |
| Обновлён | 2026/11/04 18:43 |
| Задача | 8380294 |
Аннотация
Предоставить внешним инструментам API для получения трассировок стека Java через JFR.
Цели
- Предоставить API-расширение JVMTI, которое позволит внешним инструментам получать трассировку стека для заданного потока Java.
- API безопасно для вызова из обработчиков сигналов при запросе стека текущего потока (
thread == NULL), чтобы инструменты профилирования могли вызывать его из сигналов профилирования, например при переполнении счётчика perf или по сигналам таймера CPU. - Передавать трассировку стека в виде события JFR, когда активна запись, в которой это событие включено.
- Получать трассировки стека без смещения к safepoint (safepoint bias).
Что не является целью
- Предоставлять эту функциональность для записей JFR с настройками по умолчанию не является целью. Причина в том, что создаваемые накладные расходы на производительность теперь зависят от внешнего компонента, а не от самого JFR.
- Выводить нативные фреймы не является целью. Это может быть добавлено в последующем улучшении.
Мотивация
Профилирование, то есть определение того, какую долю вычислительного ресурса (например, процессорного времени, памяти или пропускной способности сети) потребляют разные части программы, может определить, будет ли программа эффективной или неэффективной. JDK Flight Recorder (JFR) — инфраструктура профилирования платформы Java, но внешние инструменты имеют доступ к метрикам и событиям профилирования, которых JFR не предоставляет. Например, нативные инструменты профилирования на различных платформах могут измерять, сколько промахов кэша CPU или переключений контекста потоков ОС происходит в программе.
Чтобы связать эти измерения с конкретными строками кода Java-программы, нужно знать, какой код программа выполняет в момент события — например, промаха кэша или переключения контекста. Для этого требуется получать трассировку стека программы в точные моменты времени. Точнее, поскольку нативные инструменты профилирования часто порождают события профилирования в виде сигналов процессу, нужно иметь возможность запрашивать трассировки стека Java изнутри обработчиков сигналов.
Сейчас у внешних инструментов профилирования есть несколько способов получать трассировки стека, но у всех есть недостатки, из-за которых их недостаточно.
Поддерживаемый механизм, функция JVMTI GetStackTrace (и другие похожие функции JVMTI), снимает трассировку стека не в точный момент, а ждёт, пока поток дойдёт до определённых позиций в коде, называемых safepoint. Эта проблема, известная как safepoint bias (смещение к safepoint), искажает результаты профилирования: событие профилирования, например промах кэша, приписывается не тому коду. Кроме того, эту функцию небезопасно вызывать из обработчика сигналов.
Некоторые инструменты профилирования используют внутренние неподдерживаемые механизмы JVM, например функцию AsyncGetCallTrace или механизм vmStructs, описывающий структуру данных VM. Эти приёмы позволяют избежать смещения к safepoint и могут применяться внутри обработчиков сигналов, но они опасны, поскольку могут приводить к аварийному завершению или другому неопределённому поведению. Кроме того, они могут быть чувствительны к внутренним изменениям JVM, которые происходят часто. Безопасное прямое раскрытие внутреннего устройства JVM потребовало бы ограничить внутреннее развитие JVM.
JFR, встроенный в платформу механизм профилирования, получает трассировки стека безопасно и точно (т. е. без смещения). Кроме того, поскольку JFR — часть платформы и развивается вместе с JVM, а его архитектура разделяет снятие трассировки стека и её использование для анализа, он может значительно снизить стоимость получения трассировки стека. Такие оптимизации недоступны внешним механизмам и даже JVMTI, в котором снятие трассировки стека и её использование объединены в одну операцию.
Нативный API, способный запускать снятие трассировки стека средствами JFR, позволит нативным инструментам профилировать Java-программы, и пользователи смогут получать данные профилирования, которые сегодня JFR напрямую не предоставляет.
Следующий пример показывает, что даёт такой API. Это флейм-граф (flame graph), представляющий примерно 27 000 выборок промахов кэша CPU, полученных из Java-бенчмарка с помощью небольшого агента профилирования. Агент профилирования получает выборки обработчиком сигнала при переполнении счётчика perf для аппаратного счётчика cache-misses и запрашивает трассировку стека при каждом срабатывании этого сигнала.
Описание
Новая функция API — это расширение JVMTI. Её вызов запрашивает трассировку стека переданного jthread (или NULL для текущего потока), которая будет передана через JFR в событии StackTraceRequest.
Сигнатура функции:
jvmtiError RequestJFRStackTrace(jvmtiEnv* env, jthread thread, void* ucontext, jlong user_data)
Расширение JVMTI доступно под идентификатором com.sun.hotspot.functions.RequestJFRStackTrace.
Аргументы:
thread: поток Java, для которого запрашивается трассировка стека; для текущего потока передайтеNULL. Для потоков, отличных от текущего, трассировка стека может быть смещённой — см. описаниеucontext. Кроме того, API безопасно для обработчиков сигналов, только когдаthreadравенNULL. Из обработчика сигнала нельзя передавать поток, отличный отNULL. Если VM может обнаружить такой вызов, она возвращаетJVMTI_ERROR_UNSUPPORTED_OPERATION; в противном случае, например когда сигнал прервал нативный код, поведение не определено. Чтобы снять трассировку другого потока из контекста сигнала, отправьте этому потоку сигнал и вызовитеRequestJFRStackTraceсthread == NULLиз его собственного обработчика; это также даёт несмещённые трассировки стека.- При вызове с
thread==NULLиз потока Virtual Threads (виртуальные потоки) трассировка охватывает кадры этого потока Virtual Threads, и потоком события тоже является этот поток Virtual Threads. - Явная передача потока Virtual Threads в параметре thread возвращает
JVMTI_ERROR_UNSUPPORTED_OPERATION.
- При вызове с
ucontext: контекст потока (например, переданный из обработчиков сигналов POSIX). Может бытьNULL, если недоступен.- Если
thread— текущий поток (илиNULL), то передача ненулевогоucontext(к которому обработчики сигналов часто имеют доступ) может дать более точный результат, чем передачаNULL. Ненулевойucontext, не снятый вызывающей стороной функции, может привести к неопределённому поведению (включая аварийное завершение VM). - Если
threadне является текущим потоком, то при нулевомucontextзапрос ставится в очередь и взводится локальный опрос safepoint целевого потока. Стек обходится, когда целевой поток в следующий раз доходит до опроса safepoint, а если целевой поток находится в нативном коде, стек обходит внутренний поток JFR, начиная с последнего Java-кадра целевого потока. Такие трассировки смещены к safepoint. Еслиucontextне равен null, то поток должен быть приостановлен до вызова метода,ucontextдолжен быть получен, пока поток приостановлен, и поток должен оставаться приостановленным до возврата из этой функции. Если эти условия не соблюдаются, возможно неопределённое поведение (вплоть до сбоя VM).
- Если
user_data: произвольные данные, переданные вызывающей стороной. Эти данные будут возвращены в событии JFR. Обычно агент профилирования может использовать их, чтобы связать трассировку стека, выведенную JFR, с исходным событием (например, переполнением счётчика промахов кэша), которое вызвало снятие трассировки.
Функция возвращает один из следующих кодов ошибки:
JVMTI_ERROR_NONE: запрос принят; последующая потеря всё ещё возможна, см. «Доставка»JVMTI_ERROR_NOT_AVAILABLE: JFR отсутствует в сборке, рекордер JFR ещё не создан,jdk.StackTraceRequestне включено или целевой поток исключён из JFRJVMTI_ERROR_ABSENT_INFORMATION: запрос отброшен при отправке: поток находится в состоянии, в котором обход стека невозможен (например, в VM), за очередь потока идёт конкуренция или очередь заполнена. Ситуация временная; агент может учесть такой запрос или повторить попыткуJVMTI_ERROR_THREAD_NOT_ALIVE: целевой поток не запущен, завершён или завершаетсяJVMTI_ERROR_INVALID_THREAD: недействительный jthread или внутренний (скрытый) поток JVMJVMTI_ERROR_UNSUPPORTED_OPERATION: поток Virtual Threads передан явно в качествеthread; илиthread, отличный отNULL, передан вызывающей стороной, которая не может войти в VM, например из обработчика сигнала, прервавшего код Java или VM. (Вызов сthread == NULLиз такого обработчика поддерживается.)JVMTI_ERROR_UNATTACHED_THREAD: вызывающий поток не подключён к VM
Доставка
Запрос может остаться невыполненным по разным причинам:
- При отправке: об отброшенных запросах сообщается вызывающей стороне через
JVMTI_ERROR_ABSENT_INFORMATION, и отброшенный запрос также учитывается вjdk.StackTraceRequestsLost. - После отправки: потери подсчитываются для каждого потока и сообщаются в новом событии
jdk.StackTraceRequestsLost. Это запросы, отброшенные ограничением частоты, и запросы, которые всё ещё стоят в очереди, когда их поток завершается. - Неудачные обходы: неудачный обход всё равно порождает событие
jdk.StackTraceRequestсfailed = true. - Не могут быть учтены: запросы, ожидающие обработки на момент остановки записи или отключения события, поскольку записи, в которую можно было бы о них сообщить, уже нет.
Каждый запрос учитывается в записи ровно один раз: либо как событие jdk.StackTraceRequest (с failed = true, если трассировку стека получить не удалось), либо в счётчике lostRequests события jdk.StackTraceRequestsLost. Единственное исключение — запросы, ожидающие обработки на момент остановки записи или отключения события. Кроме того, о запросах, отброшенных при отправке, вызывающая сторона сразу узнаёт через JVMTI_ERROR_ABSENT_INFORMATION.
Событие JFR jdk.StackTraceRequest в статусе Experimental
Если запись JFR активна, JVM будет генерировать событие JFR jdk.StackTraceRequest в статусе Experimental (если это событие включено). У события следующие поля:
stackTrace(StackTrace): трассировка стекаeventThread(Thread): поток, стек которого был запрошен, в том числе поток Virtual Threads, если трассировка относится к немуuserData(jlong): пользовательские данные, переданные вRequestJFRStackTracefailed(boolean):true, если по какой-либо причине получить трассировку стека не удалосьbiased(boolean):true, если трассировка стека смещена к safepoint
Временная метка события соответствует моменту запроса, а не моменту обхода стека.
Событие jdk.StackTraceRequest включено в profile.jfc и отключено в default.jfc.
Событие JFR jdk.StackTraceRequestsLost в статусе Experimental
Это событие в статусе Experimental сообщает о запросах трассировки стека, которые не удалось доставить. Оно генерируется после обработанного запроса, если есть неучтённые потери, а также при завершении потока. У события следующие поля:
eventThread— платформенный поток, запросы которого были потеряны. Потери потоков Virtual Threads относятся к их несущему потоку (carrier thread).lostRequests(int): сколько запросов было потеряно
Событие jdk.StackTraceRequestsLost включено в profile.jfc и отключено в default.jfc.
Использование
Профилировщик, использующий этот API, работает так:
-
Обработчик сигнала (или любой другой триггер) вызывает
RequestJFRStackTraceс соответствующимuser_data. JFR использует механизм кооперативной выборки, чтобы получить точную трассировку стека и записать её. -
Профилировщик (или другой инструмент анализа JFR) считывает нужные события из записи JFR и при необходимости связывает их со специфичной для профилировщика информацией с помощью
user_data.
Обратите внимание: чтобы использовать эту возможность, нужно запустить запись JFR и включить событие jdk.StackTraceRequest.
Связывать собираемую внутри информацию с событием StackTraceRequest с помощью userData — обязанность внешнего инструмента профилирования. Если несколько инструментов профилирования одновременно работают с одной и той же Java-программой и оба создают одинаковые значения userData, возникнет путаница. Согласовывать потенциально конфликтующие значения userData — обязанность агентов и/или пользователя агентов.
Кроме того, JFR управляет частотой генерации события StackTraceRequest с помощью обычного механизма ограничения частоты JFR. Ограничение применяется до обхода стека, поэтому оно ограничивает фактическую стоимость обхода, а не только количество записанных событий. Событие включено только в конфигурации profile.jfc с ограничением 100/с. В конфигурации default.jfc оно отключено.
Заметки о реализации
Эта возможность использует механизм обхода стека JFR совместно с сэмплированием по процессорному времени (JEP 509: JFR CPU-Time Profiling (Experimental)), и они работают параллельно. Каждая из них сообщает о своих потерях (jdk.CPUTimeSamplesLost и jdk.StackTraceRequestsLost). Когда ни одна из них не активна, эта возможность не расходует память на очереди потоков, а её внутренний поток JFR простаивает.
Тестирование
Добавлены новые тесты jtreg:
test/jdk/jdk/jfr/jvmti: базовое использование, коды ошибок, текущий поток в качестве аргумента, чужой поток (включая учёт потерь), неактивный поток, жизненный цикл, значения по умолчанию в JFC, совместная работа с сэмплированием по процессорному времени, безопасность для сигналов, пользовательские данные, два теста для Virtual Threadstest/jdk/jdk/jfr/event/profiling/TestCPUTimeSampleNeedStackRepair.java— для пути восстановления стека в общем механизме обхода
Риски и допущения
- Контракт агента: безопасность для сигналов есть только при
thread==NULL; неправильно полученныйucontextприводит к неопределённому поведению. - Накладные расходы: ограничены лимитом частоты, который применяется до обхода.
- Память: около 1,4 КБ на поток, пока активна эта возможность или сэмплирование по процессорному времени; при постоянных потерях растёт примерно до 140 КБ на поток и освобождается, когда обе неактивны.
- Задержка: запросы для потоков в нативном коде обрабатываются внутренним потоком JFR каждые ~100 мс.
- Общий механизм: проблемы в механизме обхода стека затрагивают и эту возможность, и сэмплирование по процессорному времени.
Альтернатива
Вместо того чтобы вызывать событие JFR из функции JVMTI, функция JVMTI могла бы возвращать снятую трассировку стека вызывающему инструменту.
- Немедленный возврат трассировки стека потребовал бы при каждом вызове интерпретировать стек вызовов Java, чтобы он был понятен вызывающей стороне. Поскольку JFR разделяет снятие трассировки стека и её использование, в будущем он мог бы значительно снизить стоимость операции снятия.
- Добавление новой развитой функциональности в JVMTI разделяет работу по сопровождению функциональности профилирования в платформе между JVMTI и JFR. Большинство новых существенных возможностей профилирования мы хотели бы сосредоточить в JFR.
