.TH "Runtime_events" 3 2024-05-31 OCamldoc "OCaml library"
.SH NAME
Runtime_events \- Runtime events - ring buffer-based runtime tracing
.SH Module
Module   Runtime_events
.SH Documentation
.sp
Module
.BI "Runtime_events"
 : 
.B sig end

.sp
Runtime events \- ring buffer\-based runtime tracing
.sp
This module enables users to enable and subscribe to tracing events
from the Garbage Collector and other parts of the OCaml runtime\&. This can
be useful for diagnostic or performance monitoring purposes\&. This module
can be used to subscribe to events for the current process or external
processes asynchronously\&.
.sp
When enabled (either via setting the OCAML_RUNTIME_EVENTS_START environment
variable or calling Runtime_events\&.start) a file with the pid of the process
and extension \&.events will be created\&. By default this is in the
current directory but can be over\-ridden by the OCAML_RUNTIME_EVENTS_DIR
environment variable\&. Each domain maintains its own ring buffer in a section
of the larger file into which it emits events\&.
.sp
There is additionally a set of C APIs in runtime_events\&.h that can enable
zero\-impact monitoring of the current process or bindings for other
languages\&.
.sp
The runtime events system\&'s behaviour can be controlled by the following
environment variables:
.sp
.sp
\-OCAML_RUNTIME_EVENTS_START if set will cause the runtime events system
to be started as part of the OCaml runtime initialization\&.

.sp
\-OCAML_RUNTIME_EVENTS_DIR sets the directory where the runtime events
ring buffers will be located\&. If not present the program\&'s working directory
will be used\&.

.sp
\-OCAML_RUNTIME_EVENTS_PRESERVE if set will prevent the OCaml runtime from
removing its ring buffers when it terminates\&. This can help if monitoring
very short running programs\&.


.sp

.sp
.sp
.I type runtime_counter 
=
 | EV_C_FORCE_MINOR_ALLOC_SMALL
 | EV_C_FORCE_MINOR_MAKE_VECT
 | EV_C_FORCE_MINOR_SET_MINOR_HEAP_SIZE
 | EV_C_FORCE_MINOR_MEMPROF
 | EV_C_MINOR_PROMOTED
 | EV_C_MINOR_ALLOCATED
 | EV_C_REQUEST_MAJOR_ALLOC_SHR
 | EV_C_REQUEST_MAJOR_ADJUST_GC_SPEED
 | EV_C_REQUEST_MINOR_REALLOC_REF_TABLE
 | EV_C_REQUEST_MINOR_REALLOC_EPHE_REF_TABLE
 | EV_C_REQUEST_MINOR_REALLOC_CUSTOM_TABLE
 | EV_C_MAJOR_HEAP_POOL_WORDS  (* Total words in a Domain\&'s major heap pools\&. This is the sum of unallocated and
live words in each pool\&.

.sp
.B "Since"
5.1
 *)
 | EV_C_MAJOR_HEAP_POOL_LIVE_WORDS  (* Current live words in a Domain\&'s major heap pools\&.

.sp
.B "Since"
5.1
 *)
 | EV_C_MAJOR_HEAP_LARGE_WORDS  (* Total words of a Domain\&'s major heap large allocations\&.
A large allocation is an allocation larger than the largest sized pool\&.

.sp
.B "Since"
5.1
 *)
 | EV_C_MAJOR_HEAP_POOL_FRAG_WORDS  (* Words in a Domain\&'s major heap pools lost to fragmentation\&. This is due to
there not being a pool with the exact size of an allocation and a larger sized
pool needing to be used\&.

.sp
.B "Since"
5.1
 *)
 | EV_C_MAJOR_HEAP_POOL_LIVE_BLOCKS  (* Live blocks of a Domain\&'s major heap pools\&.

.sp
.B "Since"
5.1
 *)
 | EV_C_MAJOR_HEAP_LARGE_BLOCKS  (* Live blocks of a Domain\&'s major heap large allocations\&.

.sp
.B "Since"
5.1
 *)
 
.sp
The type for counter events emitted by the runtime\&.

.sp
.I type runtime_phase 
=
 | EV_EXPLICIT_GC_SET
 | EV_EXPLICIT_GC_STAT
 | EV_EXPLICIT_GC_MINOR
 | EV_EXPLICIT_GC_MAJOR
 | EV_EXPLICIT_GC_FULL_MAJOR
 | EV_EXPLICIT_GC_COMPACT
 | EV_MAJOR
 | EV_MAJOR_SWEEP
 | EV_MAJOR_MARK_ROOTS
 | EV_MAJOR_MARK
 | EV_MINOR
 | EV_MINOR_LOCAL_ROOTS
 | EV_MINOR_FINALIZED
 | EV_EXPLICIT_GC_MAJOR_SLICE
 | EV_FINALISE_UPDATE_FIRST
 | EV_FINALISE_UPDATE_LAST
 | EV_INTERRUPT_REMOTE
 | EV_MAJOR_EPHE_MARK
 | EV_MAJOR_EPHE_SWEEP
 | EV_MAJOR_FINISH_MARKING
 | EV_MAJOR_GC_CYCLE_DOMAINS
 | EV_MAJOR_GC_PHASE_CHANGE
 | EV_MAJOR_GC_STW
 | EV_MAJOR_MARK_OPPORTUNISTIC
 | EV_MAJOR_SLICE
 | EV_MAJOR_FINISH_CYCLE
 | EV_MINOR_CLEAR
 | EV_MINOR_FINALIZERS_OLDIFY
 | EV_MINOR_GLOBAL_ROOTS
 | EV_MINOR_LEAVE_BARRIER
 | EV_STW_API_BARRIER
 | EV_STW_HANDLER
 | EV_STW_LEADER
 | EV_MAJOR_FINISH_SWEEPING
 | EV_MINOR_FINALIZERS_ADMIN
 | EV_MINOR_REMEMBERED_SET
 | EV_MINOR_REMEMBERED_SET_PROMOTE
 | EV_MINOR_LOCAL_ROOTS_PROMOTE
 | EV_DOMAIN_CONDITION_WAIT
 | EV_DOMAIN_RESIZE_HEAP_RESERVATION
 | EV_COMPACT
 | EV_COMPACT_EVACUATE
 | EV_COMPACT_FORWARD
 | EV_COMPACT_RELEASE
 
.sp
The type for span events emitted by the runtime\&.

.sp
.I type lifecycle 
=
 | EV_RING_START
 | EV_RING_STOP
 | EV_RING_PAUSE
 | EV_RING_RESUME
 | EV_FORK_PARENT
 | EV_FORK_CHILD
 | EV_DOMAIN_SPAWN
 | EV_DOMAIN_TERMINATE
 
.sp
Lifecycle events for the ring itself\&.

.sp

.I val lifecycle_name 
: 
.B lifecycle -> string
.sp
Return a string representation of a given lifecycle event type\&.

.sp

.I val runtime_phase_name 
: 
.B runtime_phase -> string
.sp
Return a string representation of a given runtime phase event type\&.

.sp

.I val runtime_counter_name 
: 
.B runtime_counter -> string
.sp
Return a string representation of a given runtime counter type\&.

.sp
.I type cursor 

.sp
Type of the cursor used when consuming\&.

.sp
.I module Timestamp : 
.B sig end

.sp

.sp
.I module Type : 
.B sig end

.sp

.sp
.I module User : 
.B sig end

.sp

.sp
.I module Callbacks : 
.B sig end

.sp

.sp

.I val start 
: 
.B unit -> unit
.sp

.ft B
start ()
.ft R
will start the collection of events in the runtime if not already
started\&.
.sp
Events can be consumed by creating a cursor with 
.ft B
create_cursor
.ft R
and providing
a set of callbacks to be called for each type of event\&.

.sp

.I val pause 
: 
.B unit -> unit
.sp

.ft B
pause ()
.ft R
will pause the collection of events in the runtime\&.
Traces are collected if the program has called 
.ft B
Runtime_events\&.start ()
.ft R
or
the OCAML_RUNTIME_EVENTS_START environment variable has been set\&.

.sp

.I val resume 
: 
.B unit -> unit
.sp

.ft B
resume ()
.ft R
will resume the collection of events in the runtime\&.
Traces are collected if the program has called 
.ft B
Runtime_events\&.start ()
.ft R
or
the OCAML_RUNTIME_EVENTS_START environment variable has been set\&.

.sp

.I val create_cursor 
: 
.B (string * int) option -> cursor
.sp

.ft B
create_cursor path_pid
.ft R
creates a cursor to read from an runtime_events\&.
Cursors can be created for runtime_events in and out of process\&. A
runtime_events ring\-buffer may have multiple cursors reading from it at any
point in time and a program may have multiple cursors open concurrently
(for example if multiple consumers want different sets of events)\&. If
.ft B
path_pid
.ft R
is None then a cursor is created for the current process\&.
Otherwise the pair contains a string 
.ft B
path
.ft R
to the directory that contains
the 
.ft B
pid
.ft R
\&.events file and int 
.ft B
pid
.ft R
for the runtime_events of an
external process to monitor\&.

.sp

.I val free_cursor 
: 
.B cursor -> unit
.sp
Free a previously created runtime_events cursor\&.

.sp

.I val read_poll 
: 
.B cursor -> Callbacks.t -> int option -> int
.sp

.ft B
read_poll cursor callbacks max_option
.ft R
calls the corresponding functions
on 
.ft B
callbacks
.ft R
for up to 
.ft B
max_option
.ft R
events read off 
.ft B
cursor
.ft R
\&'s
runtime_events and returns the number of events read\&.

.sp