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

JEP draft: JEP Draft: Unbiased Stack-Walk JVMTI extension API

Черновик JEP: API-расширение JVMTI для обхода стека без смещения

ОтветственныйRoman Kennke
ТипFeature
ОбластьJDK
СтатусDraft
Компонентhotspot / jvmti
ТрудоёмкостьM
ДлительностьM
Создан2026/03/30 13:45
Обновлён2026/10/29 10:40
Задача8381322

Аннотация

Предоставить API, с помощью которого внешние инструменты могут запрашивать и получать несмещённые (иначе говоря, асинхронные) стеки вызовов Java. Стеки записываются в память, которую предоставляет запрашивающий JVMTI-агент.

Цели

  • Предоставить API-расширение JVMTI, которое позволяет внешним инструментам получать стек вызовов заданного Java-потока.
  • Если запрашивается стек вызовов текущего потока, API можно безопасно вызывать из обработчиков сигналов. Поэтому инструменты профилирования могут вызывать его из сигналов профилирования, например при переполнении счётчика perf или по сигналам таймера CPU.
  • API сообщает информацию о Java-фреймах: метод (в виде jmethodID), индекс байт-кода и вид фрейма.
  • API может получать стеки вызовов без смещения к safepoint (safepoint bias).
  • Агент полностью управляет памятью для стеков вызовов. Он может сам предоставить всё хранилище, позволить JVM выделить его или сочетать оба варианта.
  • Несколько агентов могут использовать API одновременно и независимо друг от друга.

Что не является целью

  • Сейчас сообщать о нативных фреймах не является целью. Это может быть добавлено в последующем улучшении.
  • Изменение или расширение спецификации JVMTI не является целью. Возможность поставляется как расширение JVMTI.
  • Вызывать код агента после того, как стек вызовов получен полностью, не является целью. Агенты сами определяют завершение (см. Завершение). Механизм уведомлений может быть добавлен позже.

Мотивация

Одно из главных преимуществ Java и JVM — обширная экосистема инструментов, которые облегчают жизнь разработчикам. Одна из категорий таких инструментов — профилировщики. В JVM есть встроенные средства профилирования (JFR). Кроме того, существуют разные внешние инструменты с более широким, а иногда и более полезным набором возможностей, как с открытым исходным кодом (например, async-profiler), так и коммерческие. Одна из ключевых возможностей, которые решения для профилирования требуют от JVM, — получение стеков вызовов. Благодаря ей инструменты профилирования могут точно показать пользователю, в каком месте его кода находятся потенциальные узкие места производительности или другие проблемы (например, промахи кэша) и каким путём программа пришла в это место.

Сейчас у внешних инструментов профилирования есть несколько способов получать стеки вызовов. У каждого из них есть недостатки, из-за которых эти способы не подходят:

  • Есть семейство официальных функций JVMTI для получения стеков вызовов: GetStackTrace, GetAllStackTraces и GetThreadListStackTraces. Эти функции принципиально небезопасны для обработчиков сигналов. Они могут выделять память и переводят вызывающий поток из состояния native в состояние VM, а это может привести к блокировке. Кроме того, они выполняют handshake или даже приводят все потоки к safepoint и ждут, пока это закончится. Стек вызовов получается только тогда, когда поток достигает safepoint. Это приводит к так называемому safepoint bias. Safepoint bias искажает результаты профилирования: горячими участками в них всегда оказываются только safepoint (например, места вызова методов или обратные переходы циклов), даже если настоящая проблема находится в другом месте.
  • Многие инструменты профилирования используют неофициальную и неподдерживаемую внутреннюю функцию JVM AsyncGetCallTrace. Она безопасна для обработчиков сигналов и не даёт safepoint bias. Однако она обходит стек вне safepoint с помощью внутреннего кода JVM, который рассчитан на работу только в safepoint, и это может привести к аварийному завершению JVM. Чтобы избежать таких сбоев, внутри JVM приходится обрабатывать всё больше особых случаев. При этом сбои можно сделать лишь маловероятными, а для стабильного решения для профилирования этого недостаточно.
  • Некоторые инструменты профилирования используют vmStructs, чтобы обходить стек своими средствами. Такой способ опасен по своей природе и не специфицирован, он может перестать работать с любым выпуском JVM. Аварийное завершение здесь почти лучший исход. Возможны и тихие, менее заметные сбои, которые труднее отлаживать.

Ниже показан пример того, что можно сделать с помощью нового API. На этом flame graph около 27 000 выборок промахов кэша CPU. Их получил небольшой агент профилирования на одной из нагрузок бенчмарка Renaissance. Агент устанавливает обработчик сигнала на переполнение аппаратного счётчика промахов кэша Linux perf и запрашивает стек вызовов каждый раз, когда срабатывает этот сигнал.

Flame-graph showing cache misses in a Renaissance workload

Описание

API состоит из трёх функций расширений JVMTI. Агент включает механизм для своего окружения JVMTI, а затем запрашивает стеки вызовов, каждый в предоставленный им буфер. JVM обходит стек запрошенного потока при его следующей проверке safepoint (safepoint poll) и записывает стек вызовов в буфер. Агент находит завершённые буферы, обычно в собственном потоке, и обрабатывает их.

Как и все функции расширений JVMTI, эти функции находят с помощью GetExtensionFunctions, а вызывать их нужно через тип с переменным числом аргументов jvmtiExtensionFunction.

Буферы

Запрос выполняется в буфер, предоставленный агентом:

typedef struct {
  jmethodID method;   // the method of the frame
  jlocation location; // the bytecode index, or -1 for native methods
  jint      type;     // JVMTI_STACK_FRAME_INTERPRETED, _COMPILED, _INLINED or _NATIVE
} jvmtiStackTraceFrame;

typedef struct jvmtiStackTraceBuffer {
  struct jvmtiStackTraceBuffer* next; // JVM: completion list link
  volatile jint status;               // JVM: JVMTI_STACK_TRACE_*
  jint frame_capacity;                // agent: number of entries in frames, may be 0
  jint max_depth;                     // agent: frames to report at most
  jint count;                         // JVM: number of frames reported
  jboolean biased;                    // JVM: the stack trace is biased towards a safepoint
  jboolean truncated;                 // JVM: the stack was deeper than max_depth
  jlong thread_id;                    // JVM: Thread.threadId() of the sampled thread, 0 if unknown
  jvmtiStackTraceFrame* frames;       // agent: storage for frame_capacity frames
  jvmtiStackTraceFrame* overflow;     // JVM: frames beyond frame_capacity, or NULL
} jvmtiStackTraceBuffer;

Поля, помеченные agent, заполняет агент. Поля, помеченные JVM, заполняет JVM.

Фреймы сообщаются от вершины стека (выполняемого в данный момент фрейма) к фрейму, с которого начался поток. Первые frame_capacity фреймов попадают в frames, все последующие — в overflow. frame_capacity — это хранилище, которое предоставляет агент. max_depth — это ограничение на количество сообщаемых фреймов в обоих массивах вместе. JVM выделяет overflow в момент обхода стека и только тогда, когда стек глубже frame_capacity, а max_depth допускает больше фреймов. Для этого используется тот же аллокатор, что и в функции JVMTI Allocate. Агент освобождает эту память с помощью Deallocate. У max_depth нет специальных значений. Оно может быть меньше frame_capacity, и тогда используется только часть хранилища. Оно может быть даже равно 0, и тогда фреймы не сообщаются вовсе. Агент, которому нужны полные стеки вызовов, выбирает ограничение, достаточное для своих целей.

Эти два поля позволяют агенту выбрать способ управления памятью:

| frame_capacity | max_depth | Хранилище фреймов | Обязанность агента | |---|---|---|---| | 0 | N | выделяется JVM | Deallocate(overflow) | | N | не более N | предоставляется только агентом; более глубокие стеки — truncated | нет | | типичная глубина | больше | предоставляется агентом, для глубоких стеков выделяется JVM | Deallocate(overflow), если не NULL |

Агент, который никогда не допускает выделения памяти со стороны JVM, задаёт max_depth не больше frame_capacity. Например, так поступает агент, который управляет фиксированным пулом заранее выделенных буферов в своём обработчике сигналов. Агент, которому нужны полные стеки вызовов без лишнего запаса памяти, предоставляет хранилище для типичной глубины стека, а для редких глубоких стеков позволяет выделять память JVM.

Запрос стека вызовов

jvmtiError RequestStackTrace(jvmtiEnv* env, jthread thread, void* ucontext, jvmtiStackTraceBuffer* buffer)
  • thread: Java-поток, для которого запрашивается стек вызовов. Для текущего потока передайте NULL. Функция безопасна для обработчиков сигналов, только когда thread равен NULL. Значение thread, отличное от NULL, нельзя передавать из обработчика сигналов. Если JVM может обнаружить такой вызов, она возвращает JVMTI_ERROR_UNSUPPORTED_OPERATION. В остальных случаях, например когда сигнал прервал нативный код, поведение не определено. Чтобы получить выборку другого потока из контекста сигнала, отправьте этому потоку сигнал и вызовите RequestStackTrace с thread == NULL из его собственного обработчика. Так тоже получаются несмещённые стеки вызовов.
    • При вызове с thread == NULL из потока Virtual Threads (виртуальные потоки) стек вызовов содержит фреймы этого потока, а thread_id указывает на этот поток.
    • Если явно передать поток Virtual Threads в качестве thread, функция вернёт JVMTI_ERROR_UNSUPPORTED_OPERATION.
  • ucontext: контекст потока, например в том виде, в каком его получают обработчики сигналов POSIX. Может быть NULL.
    • Если thread — текущий поток (или NULL), то передача ucontext текущего сигнала может дать более точный стек вызовов, чем передача NULL. Если передать ucontext, который вызывающая сторона не получила сама, поведение не определено, вплоть до аварийного завершения JVM.
    • Если thread — другой поток, а ucontext равен NULL, запрос ставится в очередь и включается локальная проверка safepoint этого потока. В этом случае стек вызовов смещён к safepoint. Если ucontext не равен NULL, поток должен быть приостановлен до вызова, а ucontext должен быть получен, пока поток приостановлен. Поток должен оставаться приостановленным, пока функция не вернёт управление. В противном случае поведение не определено.
  • buffer: буфер для стека вызовов, в котором заданы frames, frame_capacity и max_depth.

Если запрос принят, RequestStackTrace присваивает status значение JVMTI_STACK_TRACE_PENDING, и буфер принадлежит JVM, пока не будет завершён. В противном случае буфер не изменяется (кроме, возможно, status) и принадлежит агенту.

Функция возвращает один из следующих кодов ошибки:

  • JVMTI_ERROR_NONE: запрос принят. Буфер будет завершён ровно один раз (см. Завершение).
  • JVMTI_ERROR_ABSENT_INFORMATION: запрос отброшен при отправке. Например, поток находится в состоянии, в котором обход стека невозможен, или его очередь запросов заполнена. Это временное состояние, и агент может учесть такой случай или повторить попытку.
  • JVMTI_ERROR_NOT_AVAILABLE: механизм не включён для этого окружения или недоступен в этой JVM.
  • JVMTI_ERROR_THREAD_NOT_ALIVE: поток не был запущен, уже завершился или находится в процессе завершения.
  • JVMTI_ERROR_INVALID_THREAD: thread не является допустимым потоком или является внутренним потоком JVM.
  • JVMTI_ERROR_UNSUPPORTED_OPERATION: в качестве thread явно передан поток Virtual Threads. Другой вариант: значение thread, отличное от NULL, передала вызывающая сторона, которая не может войти в JVM, например обработчик сигнала, прервавший код Java или JVM. (Вызов с thread == NULL из такого обработчика поддерживается.)
  • JVMTI_ERROR_UNATTACHED_THREAD: вызывающий поток не подключён к JVM.
  • JVMTI_ERROR_NULL_POINTER: buffer равен NULL.
  • JVMTI_ERROR_ILLEGAL_ARGUMENT: frame_capacity или max_depth имеет отрицательное значение либо frames равен NULL, хотя frame_capacity не равен 0.

Завершение

Когда запрос принят, JVM завершает буфер ровно один раз с одним из следующих статусов:

  • JVMTI_STACK_TRACE_DONE: стек вызовов доступен в буфере. В нём не более max_depth фреймов. Если в стеке было больше фреймов, устанавливается truncated.
  • JVMTI_STACK_TRACE_FAILED: стек не удалось обойти или у потока не было Java-фреймов.
  • JVMTI_STACK_TRACE_DROPPED: запрос отброшен без обхода стека, потому что его поток завершился или механизм был отключён.

JVM записывает status последним, с семантикой release. Агент узнаёт о завершении одним из двух способов:

  • Список завершённых буферов. При включении механизма агент регистрирует адрес головы списка в своей собственной памяти. JVM добавляет каждый завершённый буфер в этот список неблокирующей операцией compare-and-swap и связывает буферы через next. Агент забирает все завершённые буферы сразу, атомарно заменяя голову на NULL, например в собственном потоке. Каждым буфером агент владеет с того момента, как забрал его из списка. Буферы идут в списке в обратном порядке завершения: последний завершённый идёт первым.
  • Опрос. Без списка агент читает status с семантикой acquire и владеет буфером, как только status перестаёт быть равным JVMTI_STACK_TRACE_PENDING. Пока RequestStackTrace не задаст новое значение, в status остаётся результат предыдущего запроса этого буфера. Поэтому агент, который при опросе может увидеть буфер раньше, чем RequestStackTrace вернёт управление, должен сначала сам присвоить status значение JVMTI_STACK_TRACE_PENDING.

Агент не должен обращаться к буферу или освобождать его, пока буфером владеет JVM.

Обычно запрос завершается, когда запрошенный поток доходит до своей следующей проверки safepoint. Пока поток выполняет код Java, это происходит часто. Поток, находящийся в нативном коде, периодически обрабатывается внутренним потоком JVM. Запрос для заблокированного потока остаётся в ожидании, пока поток снова не дойдёт до проверки safepoint или не завершится либо пока механизм не будет отключён.

Ссылки на методы

Методы сообщаются в виде jmethodID, которые агенты могут разрешать обычными функциями JVMTI, например GetMethodName и GetMethodDeclaringClass. jmethodID в завершённом буфере никогда не становится висячим. Если класс метода тем временем был выгружен, функции JVMTI возвращают для него JVMTI_ERROR_INVALID_METHODID. Поэтому агентам следует разрешать jmethodID без промедления, и они могут кэшировать разрешённые значения по jmethodID.

Включение и отключение

jvmtiError EnableRequestStackTrace(jvmtiEnv* env, jvmtiStackTraceBuffer** completed)
jvmtiError DisableRequestStackTrace(jvmtiEnv* env)

EnableRequestStackTrace включает механизм для окружения JVMTI, при необходимости со списком завершённых запросов (completed может быть NULL). Обычно эта функция вызывается из Agent_OnLoad; если она вызвана до инициализации JVM, механизм становится доступен после инициализации JVM. Её также можно вызвать позже. Повторное включение уже включённого окружения ни на что не влияет.

DisableRequestStackTrace отключает механизм для окружения JVMTI. Когда функция возвращает управление, каждый запрос, сделанный через это окружение, завершён и помещён в его список завершённых запросов, если такой список был зарегистрирован, а JVM больше не обращается ни к одному из его буферов и к его списку завершённых запросов. Запросы, которые ещё ожидали обработки, завершаются как JVMTI_STACK_TRACE_DROPPED. Агент должен отключить механизм, прежде чем освободить свои буферы или быть выгруженным. DisposeEnvironment неявно отключает механизм для окружения. DisableRequestStackTrace нельзя вызывать из обработчика сигнала.

Несколько агентов

Каждое окружение JVMTI использует механизм независимо. Запросы содержат собственные буферы агента, у каждого окружения свой список завершённых запросов, а включение, отключение или удаление одного окружения не влияет на запросы другого. Поэтому агентам не нужно координировать свои действия, в отличие от общего потока событий.

Однако окружения используют общие очереди запросов JVM для каждого потока, поэтому при высокой нагрузке запросы одного агента могут привести к тому, что запросы другого агента будут отброшены при отправке с JVMTI_ERROR_ABSENT_INFORMATION.

Типичное использование

Профилировщик, использующий этот API, работает так:

  1. При запуске он выделяет пул буферов, включает механизм со списком завершённых запросов и запускает собственный поток, подключённый к JVM, который опустошает этот список.
  2. Его обработчик сигнала (или любой другой триггер) берёт свободный буфер из пула без блокировок и выделения памяти и вызывает RequestStackTrace.
  3. Его поток опустошения периодически забирает завершённые буферы из списка, разрешает или кэширует jmethodID, записывает трассировки стека, освобождает все overflow с помощью Deallocate и возвращает буферы в пул.
  4. Перед выгрузкой он отключает механизм, в последний раз опустошает список и освобождает свой пул.

Реализация

Обход стека используется совместно с механизмом JFR, предложенным в JEP draft 8380294: Native Profiler Hook for Unbiased Stack Traces, который, в свою очередь, использует механизм, реализованный для JEP 509: JFR CPU-Time Profiling, и оба механизма можно использовать одновременно.

Вкратце:

  1. RequestStackTrace записывает текущие PC и SP потока, а для интерпретируемого кода — и его фрейм, и помещает запрос с адресом буфера в очередь запросов потока. При этом не выделяется память и не происходит блокировок, поэтому вызов безопасен в обработчиках сигналов.
  2. Он взводит локальную проверку safepoint потока.
  3. Когда поток доходит до следующей проверки safepoint, он обрабатывает все запросы в очереди. Поток в нативном коде не доходит до проверки safepoint, поэтому его запросы вместо этого обрабатывает внутренний поток JVM, начиная с последнего Java-фрейма потока.
  4. Для каждого запроса верхний фрейм восстанавливается по записанным PC и SP. Восстанавливать нужно только верхний фрейм (и, возможно, встроенные фреймы), потому что при возврате из метода всегда выполняется проверка safepoint.
  5. Остальная часть стека обходится обычными механизмами, и каждый фрейм записывается в буфер.
  6. Буфер завершается (см. Завершение).

Код агента никогда не вызывается во время обхода стеков. В некоторых точках, где JVM обрабатывает запросы, нельзя вызывать нативный код, а внутренний поток JVM, обрабатывающий потоки в нативном коде, не является Java-потоком. Запись в память, предоставленную агентом, вместо вызова агента позволяет избежать обеих проблем, а также любой постановки в очередь и выделения памяти внутри JVM, и не допускает потенциально медленный код агента в собственные потоки JVM.

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

  • Обратные вызовы для каждого фрейма, как в одной из ранних версий этого JEP. Поскольку код агента нельзя вызывать во время обхода стеков, JVM пришлось бы сохранять каждую трассировку стека, ставить её в очередь и доставлять позже в потоке JVM. Агенты, как правило, заново собирали бы массивы из обратных вызовов, а JVM пришлось бы управлять временем жизни обратных вызовов и потока доставки, ограничивать свою очередь и выполнять код агента в одном из своих потоков.
  • Один обратный вызов на трассировку стека с массивом, принадлежащим JVM. Это упрощает API по сравнению с обратными вызовами для каждого фрейма, но по-прежнему требует хранения, очереди и потока доставки внутри JVM.
  • Обратный вызов о завершении в дополнение к буферам, уведомляющий агента о завершённых буферах. Для него тоже потребовался бы поток доставки. Список завершённых запросов даёт большую часть преимуществ без этого; механизм уведомлений можно добавить позже, не меняя предлагаемый здесь API.
  • Реализация всей функциональности в JFR. Существует слишком много различных сценариев, например различные переполнения событий Linux perf, и многие из них зависят от платформы. JEP 509 охватывает один такой сценарий на одной платформе. JEP draft 8380294 предлагает родственное расширение JVMTI, которое выдаёт трассировки стека в виде событий JFR для инструментов, потребляющих записи JFR; там агенты используют один общий поток событий и должны координировать свои действия.
  • Изменение семейства функций JVMTI GetStackTrace так, чтобы они были безопасны для сигналов и свободны от смещения в сторону safepoint (safepoint bias). Для этого потребовалась бы новая сигнатура, принимающая ucontext, и это было бы существенным изменением поведения.
  • Исправление AsyncGetCallTrace. Его фундаментальная проблема в том, что он обходит стеки вне safepoint. Этот JEP предоставляет устойчивую замену.

Тестирование

Новые тесты jtreg с агентами, которые управляют пулами буферов и опустошают завершённые буферы в собственных потоках, проверяют:

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

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

  • Контракт агента. Доступ к буферу или его освобождение, пока им владеет JVM, отсутствие отключения механизма перед выгрузкой или передача неправильно захваченного ucontext приводят к неопределённому поведению. Эти правила сопоставимы с правилами существующих функций JVMTI, которые записывают в память, предоставленную агентом.
  • Задержка завершения. Запросы для потоков в нативном коде завершаются только тогда, когда их обрабатывает внутренний поток JVM; при высокой частоте запросов такие запросы могут быть отброшены при отправке, если очередь потока заполнена. Запросы для заблокированных потоков остаются в ожидании, пока поток не дойдёт до проверки safepoint, не завершится или пока механизм не будет отключён, поэтому агентам следует выбирать размер пулов буферов с учётом этого.
  • Общие очереди запросов. Агенты используют общие очереди запросов для каждого потока, поэтому частота запросов одного агента может привести к тому, что запросы другого агента будут отброшены при отправке.
  • Устаревшие ссылки на методы. jmethodID выгруженных классов не могут быть разрешены; агенты должны обрабатывать JVMTI_ERROR_INVALID_METHODID.
  • Общий механизм. Проблемы в обходчике стека затрагивают как этот механизм, так и его использование в JFR.

Открытые вопросы

  • Сообщение идентификатора потока для Virtual Threads в нативном коде, которые обрабатываются внутренним потоком JVM.
  • Следует ли сообщать полную глубину стека при усечении трассировки стека, чтобы помочь агентам выбрать размер буферов.
  • Необязательный механизм уведомления о завершённых буферах, например eventfd или futex, через который JVM подаёт сигнал, для агентов, которые не хотят использовать опрос.
  • Нужны ли ограничения для каждого агента на общие очереди запросов, чтобы обеспечить справедливость между агентами.