Runtime_eventsRuntime events - ring buffer-based runtime tracing
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.
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.
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.
The runtime events system's behaviour can be controlled by the following environment variables:
type runtime_counter = | EV_C_FORCE_MINOR_ALLOC_SMALLTriggering of a minor collection due to a full minor heap.
*)| EV_C_FORCE_MINOR_MAKE_VECTTriggering of a minor collection due to Array.make.
*)| EV_C_FORCE_MINOR_SET_MINOR_HEAP_SIZETriggering of a minor collection due to Gc.minor_heap_size.
*)| EV_C_FORCE_MINOR_MEMPROFTriggering of a minor collection during memprof young sampling.
*)| EV_C_MINOR_PROMOTEDTotal words promoted from the minor heap to the major in the last minor collection.
*)| EV_C_MINOR_ALLOCATEDTotal bytes allocated in the minor heap in the last minor collection.
*)| EV_C_REQUEST_MAJOR_ALLOC_SHRMajor slice requested due to allocation in major heap.
*)| EV_C_REQUEST_MAJOR_ADJUST_GC_SPEEDMajor slice requested by caml_adjust_gc_speed.
| EV_C_REQUEST_MINOR_REALLOC_REF_TABLETriggering of a minor collection due to ref table reallocation.
*)| EV_C_REQUEST_MINOR_REALLOC_EPHE_REF_TABLETriggering of a minor collection due to ephe_ref table reallocation.
*)| EV_C_REQUEST_MINOR_REALLOC_CUSTOM_TABLETriggering of a minor collection due to custom table reallocation.
*)| EV_C_MAJOR_HEAP_POOL_WORDSTotal words in a Domain's major heap pools. This is the sum of unallocated and live words in each pool.
*)| EV_C_MAJOR_HEAP_POOL_LIVE_WORDSCurrent live words in a Domain's major heap pools.
*)| EV_C_MAJOR_HEAP_LARGE_WORDSTotal words of a Domain's major heap large allocations. A large allocation is an allocation larger than the largest sized pool.
*)| EV_C_MAJOR_HEAP_POOL_FRAG_WORDSWords 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.
*)| EV_C_MAJOR_HEAP_POOL_LIVE_BLOCKSLive blocks of a Domain's major heap pools.
*)| EV_C_MAJOR_HEAP_LARGE_BLOCKSLive blocks of a Domain's major heap large allocations.
*)| EV_C_MAJOR_HEAP_WORDSMajor heap size in words of a Domain.
*)| EV_C_MAJOR_ALLOCATED_WORDSAllocations to the major heap of this Domain in words, since the last major slice.
*)| EV_C_MAJOR_ALLOCATED_WORKThe amount of major GC 'work' needing to be done as a result of allocations to the major heap of this Domain in words, since the last major slice.
*)| EV_C_MAJOR_DEPENDENT_WORKThe amount of major GC 'work' needing to be done as a result of dependent allocations to the major heap of this Domain in words, since the last major slice. Dependent memory is non-heap memory that depends on heap memory being collected in order to be freed.
*)| EV_C_MAJOR_EXTRA_WORKThe amount of major GC 'work' needing to be done as a result of extra non-memory resources that are dependent on heap memory being collected in order to be freed.
*)| EV_C_MAJOR_WORK_COUNTERThe global amount of major GC 'work' done by all domains since the program began.
*)| EV_C_MAJOR_ALLOC_COUNTERThe global words of major GC allocations done by all domains since the program began.
*)| EV_C_MAJOR_SLICE_TARGETThe target amount of global 'work' that should be done by all domains at the end of the major slice (see EV_C_MAJOR_SLICE_COUNTER).
*)| EV_C_MAJOR_SLICE_BUDGETThe budget in 'work' that a domain has to do during the major slice.
*)The type for counter events emitted by the runtime. Counter events are used to measure a quantity at a point in time or record the occurence of an event. In the latter case their value will be one.
type runtime_phase = | EV_EXPLICIT_GC_SETEvent spanning a call to Gc.set.
*)| EV_EXPLICIT_GC_STATEvent spanning a call to Gc.stat.
*)| EV_EXPLICIT_GC_MINOREvent spanning a call to Gc.minor, which forces a minor collection.
*)| EV_EXPLICIT_GC_MAJOREvent spanning a call to Gc.major, which forces a major collection.
*)| EV_EXPLICIT_GC_FULL_MAJOREvent spanning a call to Gc.full_major, which forces a full major collection.
*)| EV_EXPLICIT_GC_COMPACTEvent spanning a call to Gc.compact, which triggers a compaction.
*)| EV_MAJOREvent spanning any major GC work.
*)| EV_MAJOR_SWEEPEvent spanning the sweeping work of a major GC.
*)| EV_MAJOR_MARK_ROOTSEvent spanning the marking of roots in a major GC.
*)| EV_MAJOR_MEMPROF_ROOTSEvent spanning the marking of memprof roots in a major GC.
*)| EV_MAJOR_MARKEvent spanning the marking of the heap in a major GC.
*)| EV_MINOREvent spanning any minor GC work.
*)| EV_MINOR_LOCAL_ROOTSEvent spanning the scanning and major allocation of local roots during a minor GC.
*)| EV_MINOR_MEMPROF_ROOTSEvent spanning the scanning and promotion of memprof roots in a minor GC.
*)| EV_MINOR_MEMPROF_CLEANEvent spanning cleaning and updating of memprof structures at the end of a minor GC.
*)| EV_MINOR_FINALIZEDEvent spanning the running of finalisers for dead custom blocks at the end of a minor GC.
*)| EV_EXPLICIT_GC_MAJOR_SLICEEvent spanning a call to Gc.major_slice.
*)| EV_FINALISE_UPDATE_FIRSTEvent spanning time spent in the first phase of finalisation at the end of a major GC cycle.
*)| EV_FINALISE_UPDATE_LASTEvent spanning time spent in the last phase of finalisation at the end of a major GC cycle.
*)| EV_INTERRUPT_REMOTEEvent spanning work triggered by an interrupt from another domain. This is usually a stop-the-world request.
*)| EV_MAJOR_EPHE_MARKEvent spanning the marking of ephemeron tables in a major GC.
*)| EV_MAJOR_EPHE_SWEEPEvent spanning the sweeping of ephemeron tables in a major GC.
*)| EV_MAJOR_FINISH_MARKINGEvent spanning work done at the end of marking in a major GC.
*)| EV_MAJOR_GC_CYCLE_DOMAINSEvent spanning work done at the end of a major GC cycle. This includes a minor collection.
*)| EV_MAJOR_GC_PHASE_CHANGEEvent spanning the change of phase in the major GC which involves a global barrier.
*)| EV_MAJOR_GC_STWEvent spanning the stop-the-world phase done at the end of a major GC cycle.
*)| EV_MAJOR_MARK_OPPORTUNISTICEvent spanning the work done during opportunistic marking in a major GC.
*)| EV_MAJOR_SLICEEvent spanning the work done during a major slice in a major GC.
*)| EV_MAJOR_FINISH_CYCLEEvent spanning attempts to drive all domains to the end of a major GC cycle.
*)| EV_MINOR_CLEAREvent spanning the cleaning of the minor heap and supporting structures at the end of a minor GC.
*)| EV_MINOR_FINALIZERS_OLDIFYEvent spanning the promotion of finalisers during a minor GC.
*)| EV_MINOR_GLOBAL_ROOTSEvent spanning the scanning and major allocation of global roots during a minor GC.
*)| EV_MINOR_LEAVE_BARRIEREvent spanning the time spent in the barrier at the end of a minor GC, waiting for all domains to finish their work.
*)| EV_STW_API_BARRIEREvent spanning the time spent waiting for all other domains to reach the stop-the-world entry barrier.
*)| EV_STW_HANDLEREvent spanning the time spent in the stop-the-world handler, including time spent in the stop-the-world callback itself.
*)| EV_STW_LEADEREvent spanning the time spent as the leader of a stop-the-world.
*)| EV_MAJOR_FINISH_SWEEPINGEvent spanning the time spent finishing sweeping when forced to as part of domain termination.
*)| EV_MAJOR_MEMPROF_CLEANEvent spanning the time spent cleaning memprof structures at the end of a major GC.
*)| EV_MINOR_FINALIZERS_ADMINEvent spanning finalisers book-keeping at the end of a minor GC.
*)| EV_MINOR_REMEMBERED_SETEvent spanning the scanning and major allocation of remembered sets during a minor GC.
*)| EV_MINOR_REMEMBERED_SET_PROMOTEEvent spanning the promotion of blocks in the remembered set and global roots during a minor GC.
*)| EV_MINOR_LOCAL_ROOTS_PROMOTEEvent spanning the promotion of local roots during a minor GC.
*)| EV_DOMAIN_CONDITION_WAITEvent spanning waiting in Condition.wait.
*)| EV_DOMAIN_RESIZE_HEAP_RESERVATIONEvent spanning resizing the domain heap reservation, as a result of minor heap size changes.
*)| EV_COMPACTEvent spanning compaction of the heap during a call to Gc.compact.
*)| EV_COMPACT_EVACUATEEvent spanning evacuating major GC pools during a compaction.
*)| EV_COMPACT_FORWARDEvent spanning the walking of the heap to update changed pointers after an evacuation during a compaction.
*)| EV_COMPACT_RELEASEEvent spanning releasing the evacuated pools at the end of a compaction.
*)The type for span events emitted by the runtime.
type lifecycle = | EV_RING_STARTEvent indicating that the Runtime_events ring buffer has been started. Includes the PID of the process as an argument.
*)| EV_RING_STOPEvent indicating that the Runtime_events ring buffer has been stopped.
*)| EV_RING_PAUSEEvent indicating that the Runtime_events ring buffer has been paused.
*)| EV_RING_RESUMEEvent indicating that the Runtime_events ring buffer has been resumed.
*)| EV_FORK_PARENTEvent indicating that a fork has occurred and the current domain is the parent. Includes the PID of the child as an argument.
*)| EV_FORK_CHILDEvent indicating that a fork has occurred and the current domain is the child.
*)| EV_DOMAIN_SPAWNEvent indicating that a new domain has been spawned. Includes the PID of the new domain as an argument.
*)| EV_DOMAIN_TERMINATEEvent indicating that a domain has terminated. Includes the PID of the domain as an argument.
*)Lifecycle events for Runtime_events and domains.
val lifecycle_name : lifecycle -> stringReturn a string representation of a given lifecycle event type.
val runtime_phase_name : runtime_phase -> stringReturn a string representation of a given runtime phase event type.
val runtime_counter_name : runtime_counter -> stringReturn a string representation of a given runtime counter type.
module Timestamp : sig ... endmodule Type : sig ... endmodule User : sig ... endUser events is a way for libraries to provide runtime events that can be consumed by other tools. These events can carry known data types or custom values. The current maximum number of user events is 8192.
module Callbacks : sig ... endstart () will start the collection of events in the runtime if not already started.
Events can be consumed by creating a cursor with create_cursor and providing a set of callbacks to be called for each type of event.
If runtime events are being collected, path () returns Some p where p is a path to the runtime events file. Otherwise, it returns None.
pause () will pause the collection of events in the runtime. Traces are collected if the program has called Runtime_events.start () or the OCAML_RUNTIME_EVENTS_START environment variable has been set.
resume () will resume the collection of events in the runtime. Traces are collected if the program has called Runtime_events.start () or the OCAML_RUNTIME_EVENTS_START environment variable has been set.
val create_cursor : (string * int) option -> cursorcreate_cursor path_pid 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 path_pid is None then a cursor is created for the current process. Otherwise the pair contains a string path to the directory that contains the pid.events file and int pid for the runtime_events of an external process to monitor.
val free_cursor : cursor -> unitFree a previously created runtime_events cursor.
val read_poll : cursor -> Callbacks.t -> int option -> intread_poll cursor callbacks max_option calls the corresponding functions on callbacks for up to max_option events read off cursor's runtime_events and returns the number of events read.