openjdk.ruOpenJDK на русском

JEP draft: Native Profiler Hook for Unbiased Stack Traces (Experimental)

Нативный хук профилировщика для получения трассировок стека без смещения (в статусе Experimental (экспериментальная функция))

AuthorsRoman 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 и запрашивает трассировку стека при каждом срабатывании этого сигнала.

Flame graph showing cache misses in a Renaissance workload

Описание

Новая функция 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 не включено или целевой поток исключён из JFR
  • JVMTI_ERROR_ABSENT_INFORMATION: запрос отброшен при отправке: поток находится в состоянии, в котором обход стека невозможен (например, в VM), за очередь потока идёт конкуренция или очередь заполнена. Ситуация временная; агент может учесть такой запрос или повторить попытку
  • JVMTI_ERROR_THREAD_NOT_ALIVE: целевой поток не запущен, завершён или завершается
  • JVMTI_ERROR_INVALID_THREAD: недействительный jthread или внутренний (скрытый) поток JVM
  • JVMTI_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): пользовательские данные, переданные в RequestJFRStackTrace
  • failed (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, работает так:

  1. Обработчик сигнала (или любой другой триггер) вызывает RequestJFRStackTrace с соответствующим user_data. JFR использует механизм кооперативной выборки, чтобы получить точную трассировку стека и записать её.

  2. Профилировщик (или другой инструмент анализа 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 Threads
  • test/jdk/jdk/jfr/event/profiling/TestCPUTimeSampleNeedStackRepair.java — для пути восстановления стека в общем механизме обхода

Риски и допущения

  • Контракт агента: безопасность для сигналов есть только при thread == NULL; неправильно полученный ucontext приводит к неопределённому поведению.
  • Накладные расходы: ограничены лимитом частоты, который применяется до обхода.
  • Память: около 1,4 КБ на поток, пока активна эта возможность или сэмплирование по процессорному времени; при постоянных потерях растёт примерно до 140 КБ на поток и освобождается, когда обе неактивны.
  • Задержка: запросы для потоков в нативном коде обрабатываются внутренним потоком JFR каждые ~100 мс.
  • Общий механизм: проблемы в механизме обхода стека затрагивают и эту возможность, и сэмплирование по процессорному времени.

Альтернатива

Вместо того чтобы вызывать событие JFR из функции JVMTI, функция JVMTI могла бы возвращать снятую трассировку стека вызывающему инструменту.

  • Немедленный возврат трассировки стека потребовал бы при каждом вызове интерпретировать стек вызовов Java, чтобы он был понятен вызывающей стороне. Поскольку JFR разделяет снятие трассировки стека и её использование, в будущем он мог бы значительно снизить стоимость операции снятия.
  • Добавление новой развитой функциональности в JVMTI разделяет работу по сопровождению функциональности профилирования в платформе между JVMTI и JFR. Большинство новых существенных возможностей профилирования мы хотели бы сосредоточить в JFR.