Модуль Runtime_events

module Runtime_events: sig .. end

Runtime events — трассировка выполнения на основе кольцевого буфера

Этот модуль позволяет пользователям включать трассировку событий сборщика мусора и других частей среды выполнения OCaml и подписываться на них. Это может быть полезно для диагностики или мониторинга производительности. Модуль позволяет асинхронно подписываться на события текущего процесса или внешних процессов.

При включении (через переменную среды OCAML_RUNTIME_EVENTS_START или вызов Runtime_events.start) будет создан файл с идентификатором процесса (pid) и расширением .events. По умолчанию файл создаётся в текущем каталоге, но это можно изменить с помощью переменной среды OCAML_RUNTIME_EVENTS_DIR. Каждый домен хранит собственный кольцевой буфер в отдельной области большего файла, куда записывает события.

Кроме того, в runtime_events.h имеется набор C API, позволяющих осуществлять мониторинг текущего процесса с нулевым влиянием на его работу или создавать привязки для других языков.

Поведение системы событий среды выполнения можно контролировать с помощью следующих переменных среды:

Если задана OCAML_RUNTIME_EVENTS_START, система событий среды выполнения запускается при инициализации среды выполнения OCaml.

OCAML_RUNTIME_EVENTS_DIR задаёт каталог, в котором будут находиться кольцевые буферы событий среды выполнения. Если переменная не задана, используется рабочий каталог программы.

Если задана OCAML_RUNTIME_EVENTS_PRESERVE, среда выполнения OCaml не удаляет кольцевые буферы при завершении. Это может быть полезно при мониторинге программ с очень коротким временем выполнения.

type runtime_counter =

`\|`	`EV_C_FORCE_MINOR_ALLOC_SMALL`	`(*`	Запуск младшей сборки из-за заполнения младшей кучи. Начиная с версии 5.0	`*)`
`\|`	`EV_C_FORCE_MINOR_MAKE_VECT`	`(*`	Запуск младшей сборки из-за Array.make. Начиная с версии 5.0	`*)`
`\|`	`EV_C_FORCE_MINOR_SET_MINOR_HEAP_SIZE`	`(*`	Запуск младшей сборки из-за Gc.minor_heap_size. Начиная с версии 5.0	`*)`
`\|`	`EV_C_FORCE_MINOR_MEMPROF`	`(*`	Запуск младшей сборки во время отбора молодых объектов для memprof. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MINOR_PROMOTED`	`(*`	Общее количество байтов, перенесённых из младшей кучи этого домена в старшую кучу во время последней младшей сборки. Начиная с версии 5.0	`*)`
`\|`	`EV_C_MINOR_ALLOCATED`	`(*`	Общее количество байтов, выделенных в младшей куче этого домена во время последней младшей сборки. Начиная с версии 5.0	`*)`
`\|`	`EV_C_REQUEST_MAJOR_ALLOC_SHR`	`(*`	Запрос среза старшей сборки из-за выделения памяти в старшей куче. Начиная с версии 5.0	`*)`
`\|`	`EV_C_REQUEST_MAJOR_ADJUST_GC_SPEED`	`(*`	Срез старшей сборки запрошен событием `caml_adjust_gc_speed`. Начиная с версии 5.0	`*)`
`\|`	`EV_C_REQUEST_MINOR_REALLOC_REF_TABLE`	`(*`	Запуск младшей сборки из-за перераспределения таблицы ссылок. Начиная с версии 5.0	`*)`
`\|`	`EV_C_REQUEST_MINOR_REALLOC_EPHE_REF_TABLE`	`(*`	Запуск младшей сборки из-за перераспределения таблицы ephe_ref. Начиная с версии 5.0	`*)`
`\|`	`EV_C_REQUEST_MINOR_REALLOC_CUSTOM_TABLE`	`(*`	Запуск младшей сборки из-за перераспределения пользовательской таблицы. Начиная с версии 5.0	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_WORDS`	`(*`	Общее количество слов в пулах старшей кучи домена. Это сумма невыделенных и занятых слов в каждом пуле. Начиная с версии 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_LIVE_WORDS`	`(*`	Текущее количество занятых слов в пулах старшей кучи домена. Начиная с версии 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_LARGE_WORDS`	`(*`	Общее количество слов в крупных выделениях старшей кучи домена. Крупным считается выделение, размер которого превышает размер самого большого пула. Начиная с версии 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_FRAG_WORDS`	`(*`	Количество слов в пулах старшей кучи домена, потерянных из-за фрагментации. Это происходит, когда нет пула точного размера для выделения и приходится использовать пул большего размера. Начиная с версии 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_POOL_LIVE_BLOCKS`	`(*`	Количество живых блоков в пулах старшей кучи домена. Начиная с версии 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_LARGE_BLOCKS`	`(*`	Количество живых блоков в крупных выделениях старшей кучи домена. Начиная с версии 5.1	`*)`
`\|`	`EV_C_MAJOR_HEAP_WORDS`	`(*`	Размер старшей кучи домена в словах. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_ALLOCATED_WORDS`	`(*`	Выделения в старшей куче этого домена в словах с момента последнего среза старшей сборки. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_ALLOCATED_WORK`	`(*`	Объём «работы» старшей сборки, которую необходимо выполнить из-за выделений в старшей куче этого домена в словах с момента последнего среза старшей сборки. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_DEPENDENT_WORK`	`(*`	Объём «работы» старшей сборки, которую необходимо выполнить из-за зависимых выделений в старшей куче этого домена в словах с момента последнего среза старшей сборки. Зависимая память — это память вне кучи, освобождение которой зависит от сборки памяти в куче. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_EXTRA_WORK`	`(*`	Объём «работы» старшей сборки, которую необходимо выполнить из-за дополнительных ресурсов, не являющихся памятью, освобождение которых зависит от сборки памяти в куче. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_WORK_COUNTER`	`(*`	Общий объём «работы» старшей сборки, выполненной всеми доменами с момента запуска программы. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_ALLOC_COUNTER`	`(*`	Общий объём выделений старшей сборки всеми доменами с момента запуска программы в словах. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_SLICE_TARGET`	`(*`	Целевой объём общей «работы», который должны выполнить все домены к концу среза старшей сборки (см. EV_C_MAJOR_SLICE_COUNTER). Начиная с версии 5.3	`*)`
`\|`	`EV_C_MAJOR_SLICE_BUDGET`	`(*`	Бюджет «работы», которую домен должен выполнить во время среза старшей сборки. Начиная с версии 5.3	`*)`
`\|`	`EV_C_MINOR_ALLOCATED_WORDS`	`(*`	Общее количество слов, выделенных в младшей куче этого домена во время последней младшей сборки. Начиная с версии 5.4	`*)`
`\|`	`EV_C_MINOR_PROMOTED_WORDS`	`(*`	Общее количество слов, перенесённых из младшей кучи этого домена в старшую кучу во время последней младшей сборки. Начиная с версии 5.4	`*)`

Тип событий-счётчиков, генерируемых средой выполнения. События-счётчики используются для измерения величины в определённый момент времени или регистрации наступления события. Во втором случае их значение равно единице.

type runtime_phase =

`\|`	`EV_EXPLICIT_GC_SET`	`(*`	Событие, охватывающее вызов Gc.set. Начиная с версии 5.0	`*)`
`\|`	`EV_EXPLICIT_GC_STAT`	`(*`	Событие, охватывающее вызов Gc.stat. Начиная с версии 5.0	`*)`
`\|`	`EV_EXPLICIT_GC_MINOR`	`(*`	Событие, охватывающее вызов Gc.minor, который запускает малую сборку мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_EXPLICIT_GC_MAJOR`	`(*`	Событие, охватывающее вызов Gc.major, который запускает большую сборку мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_EXPLICIT_GC_FULL_MAJOR`	`(*`	Событие, охватывающее вызов Gc.full_major, который запускает полную большую сборку мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_EXPLICIT_GC_COMPACT`	`(*`	Событие, охватывающее вызов Gc.compact, который запускает уплотнение. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR`	`(*`	Событие, охватывающее любые работы большой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_SWEEP`	`(*`	Событие, охватывающее очистку при большой сборке мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_MARK_ROOTS`	`(*`	Событие, охватывающее маркировку корней при большой сборке мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_MEMPROF_ROOTS`	`(*`	Событие, охватывающее маркировку корней memprof при большой сборке мусора. Начиная с версии 5.3	`*)`
`\|`	`EV_MAJOR_MARK`	`(*`	Событие, охватывающее маркировку кучи при большой сборке мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR`	`(*`	Событие, охватывающее любые работы малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_LOCAL_ROOTS`	`(*`	Событие, охватывающее сканирование локальных корней и выделение памяти в области большой кучи во время малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_MEMPROF_ROOTS`	`(*`	Событие, охватывающее сканирование и продвижение корней memprof во время малой сборки мусора. Начиная с версии 5.3	`*)`
`\|`	`EV_MINOR_MEMPROF_CLEAN`	`(*`	Событие, охватывающее очистку и обновление структур memprof в конце малой сборки мусора. Начиная с версии 5.3	`*)`
`\|`	`EV_MINOR_FINALIZED`	`(*`	Событие, охватывающее запуск финализаторов для мёртвых пользовательских блоков в конце малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_EXPLICIT_GC_MAJOR_SLICE`	`(*`	Событие, охватывающее вызов Gc.major_slice. Начиная с версии 5.0	`*)`
`\|`	`EV_FINALISE_UPDATE_FIRST`	`(*`	Событие, охватывающее время, затраченное на первый этап финализации в конце цикла большой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_FINALISE_UPDATE_LAST`	`(*`	Событие, охватывающее время, затраченное на последний этап финализации в конце цикла большой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_INTERRUPT_REMOTE`	`(*`	Событие, охватывающее работу, вызванную прерыванием из другого домена. Обычно это запрос на остановку мира. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_EPHE_MARK`	`(*`	Событие, охватывающее маркировку таблиц эфемеронов при большой сборке мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_EPHE_SWEEP`	`(*`	Событие, охватывающее очистку таблиц эфемеронов при большой сборке мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_FINISH_MARKING`	`(*`	Событие, охватывающее работы, выполняемые в конце этапа маркировки при большой сборке мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_GC_CYCLE_DOMAINS`	`(*`	Событие, охватывающее работы, выполняемые в конце цикла большой сборки мусора. Включает малую сборку мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_GC_PHASE_CHANGE`	`(*`	Событие, охватывающее смену фазы большой сборки мусора, для которой требуется глобальный барьер. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_GC_STW`	`(*`	Событие, охватывающее фазу остановки мира, выполняемую в конце цикла большой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_MARK_OPPORTUNISTIC`	`(*`	Событие, охватывающее работу, выполняемую при оппортунистической маркировке во время большой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_SLICE`	`(*`	Событие, охватывающее работу, выполняемую во время большого фрагмента большой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_FINISH_CYCLE`	`(*`	Событие, охватывающее попытки довести все домены до конца цикла большой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_CLEAR`	`(*`	Событие, охватывающее очистку малой кучи и вспомогательных структур в конце малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_FINALIZERS_OLDIFY`	`(*`	Событие, охватывающее продвижение финализаторов во время малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_GLOBAL_ROOTS`	`(*`	Событие, охватывающее сканирование глобальных корней и выделение памяти в области большой кучи во время малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_LEAVE_BARRIER`	`(*`	Событие, охватывающее время ожидания у барьера в конце малой сборки мусора, пока все домены не завершат свою работу. Начиная с версии 5.0	`*)`
`\|`	`EV_STW_API_BARRIER`	`(*`	Событие, охватывающее время ожидания, пока все остальные домены не достигнут входного барьера остановки мира. Начиная с версии 5.0	`*)`
`\|`	`EV_STW_HANDLER`	`(*`	Событие, охватывающее время работы обработчика остановки мира, включая время выполнения самого обратного вызова остановки мира. Начиная с версии 5.0	`*)`
`\|`	`EV_STW_LEADER`	`(*`	Событие, охватывающее время, проведённое в роли ведущего остановки мира. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_FINISH_SWEEPING`	`(*`	Событие, охватывающее время, затраченное на завершение очистки, если это требуется при завершении домена. Начиная с версии 5.0	`*)`
`\|`	`EV_MAJOR_MEMPROF_CLEAN`	`(*`	Событие, охватывающее время, затраченное на очистку структур memprof в конце большой сборки мусора. Начиная с версии 5.3	`*)`
`\|`	`EV_MINOR_FINALIZERS_ADMIN`	`(*`	Событие, охватывающее учёт финализаторов в конце малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_REMEMBERED_SET`	`(*`	Событие, охватывающее сканирование наборов запомненных ссылок и выделение памяти в области большой кучи во время малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_REMEMBERED_SET_PROMOTE`	`(*`	Событие, охватывающее продвижение блоков в наборе запомненных ссылок и глобальных корней во время малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_MINOR_LOCAL_ROOTS_PROMOTE`	`(*`	Событие, охватывающее продвижение локальных корней во время малой сборки мусора. Начиная с версии 5.0	`*)`
`\|`	`EV_DOMAIN_CONDITION_WAIT`	`(*`	Событие, охватывающее ожидание в Condition.wait. Начиная с версии 5.0	`*)`
`\|`	`EV_DOMAIN_RESIZE_HEAP_RESERVATION`	`(*`	Событие, охватывающее изменение размера резерва кучи домена в результате изменения размера малой кучи. Начиная с версии 5.0	`*)`
`\|`	`EV_COMPACT`	`(*`	Событие, охватывающее уплотнение кучи во время вызова Gc.compact. Начиная с версии 5.2	`*)`
`\|`	`EV_COMPACT_EVACUATE`	`(*`	Событие, охватывающее эвакуацию пулов большой сборки мусора во время уплотнения. Начиная с версии 5.2	`*)`
`\|`	`EV_COMPACT_FORWARD`	`(*`	Событие, охватывающее обход кучи для обновления изменившихся указателей после эвакуации во время уплотнения. Начиная с версии 5.2	`*)`
`\|`	`EV_COMPACT_RELEASE`	`(*`	Событие, охватывающее освобождение эвакуированных пулов в конце уплотнения. Начиная с версии 5.2	`*)`
`\|`	`EV_EMPTY_MINOR`	`(*`	Событие, охватывающее освобождение малой кучи домена для нового выделения памяти. Сюда входит время, затраченное на попытки стать ведущим остановки мира. Начиная с версии 5.4	`*)`

Тип событий-интервалов, генерируемых средой выполнения.

type lifecycle =

`\|`	`EV_RING_START`	`(*`	Событие, указывающее, что кольцевой буфер Runtime_events запущен. В качестве аргумента содержит PID процесса. С версии 5.0	`*)`
`\|`	`EV_RING_STOP`	`(*`	Событие, указывающее, что кольцевой буфер Runtime_events остановлен. С версии 5.0	`*)`
`\|`	`EV_RING_PAUSE`	`(*`	Событие, указывающее, что кольцевой буфер Runtime_events приостановлен. С версии 5.0	`*)`
`\|`	`EV_RING_RESUME`	`(*`	Событие, указывающее, что сбор событий в кольцевом буфере Runtime_events возобновлён. С версии 5.0	`*)`
`\|`	`EV_FORK_PARENT`	`(*`	Событие, указывающее, что произошло порождение процесса и текущий домен является родительским. В качестве аргумента содержит PID дочернего процесса. С версии 5.0	`*)`
`\|`	`EV_FORK_CHILD`	`(*`	Событие, указывающее, что произошло порождение процесса и текущий домен является дочерним. С версии 5.0	`*)`
`\|`	`EV_DOMAIN_SPAWN`	`(*`	Событие, указывающее, что был создан новый домен. В качестве аргумента содержит PID нового домена. С версии 5.0	`*)`
`\|`	`EV_DOMAIN_TERMINATE`	`(*`	Событие, указывающее, что домен завершил работу. В качестве аргумента содержит PID домена. С версии 5.0	`*)`

События жизненного цикла Runtime_events и доменов.

val lifecycle_name : lifecycle -> string

Возвращает строковое представление заданного типа события жизненного цикла.

val runtime_phase_name : runtime_phase -> string

Возвращает строковое представление заданного типа события фазы выполнения.

val runtime_counter_name : runtime_counter -> string

Возвращает строковое представление заданного типа счётчика времени выполнения.

type cursor

Тип курсора, используемого при чтении.

module Timestamp: sig .. end

module Type: sig .. end

module User: sig .. end

module Callbacks: sig .. end

val start : unit -> unit

start () запустит сбор событий во время выполнения, если он ещё не запущен.

События можно считывать, создав курсор с помощью create_cursor и передав набор обратных вызовов, которые будут вызываться для каждого типа события.

val path : unit -> string option

Если события времени выполнения собираются, path () возвращает Some p, где p — путь к файлу событий времени выполнения. В противном случае возвращает None.

val pause : unit -> unit

pause () приостанавливает сбор событий во время выполнения. Трассировки собираются, если программа вызвала Runtime_events.start () или задана переменная окружения OCAML_RUNTIME_EVENTS_START.

val resume : unit -> unit

resume () возобновляет сбор событий во время выполнения. Трассировки собираются, если программа вызвала Runtime_events.start () или задана переменная окружения OCAML_RUNTIME_EVENTS_START.

val create_cursor : (string * int) option -> cursor

create_cursor path_pid создаёт курсор для чтения из runtime_events. Курсоры можно создавать для runtime_events внутри и вне процесса. Из кольцевого буфера runtime_events одновременно могут считывать данные несколько курсоров, а программа может одновременно открыть несколько курсоров (например, если нескольким потребителям нужны разные наборы событий). Если path_pid равен None, курсор создаётся для текущего процесса. В противном случае пара содержит строку path — путь к каталогу, в котором находится файл pid.events, — и целое число pid для runtime_events внешнего процесса, за которым нужно следить.

val free_cursor : cursor -> unit

Освобождает ранее созданный курсор runtime_events.

val read_poll : cursor -> Callbacks.t -> int option -> int

read_poll cursor callbacks max_option вызывает соответствующие функции для callbacks не более чем для max_option событий, считанных из runtime_events процесса cursor, и возвращает число считанных событий.