Runtime_events(3)

📦
version 5.5.0 · 13 versions
, in arch rolling

💖 Runtime_events(3) — ring buffer-based runtime tracing 💖

okay so this is the Runtime_events page from the OCaml library manual, and it's literally the group chat for the OCaml runtime's tea ☕ — ring-buffer tracing, bestie. Let's get into it.

🌸 NAME 🌸

Runtime_events — Runtime events - ring buffer-based runtime tracing

🎀 Module 🎀

Module Runtime_events

Module Runtime_events : sig end

✨ Documentation ✨

okay so Runtime_events is the module that lets you enable and subscribe to tracing events from the Garbage Collector and other parts of the OCaml runtime. It's giving diagnostic/performance-monitoring main character energy 💅 — super useful for diagnostics or performance monitoring purposes.

You can use this module to subscribe to events for the current process or external processes asynchronously. No cap.

When enabled — either by setting the OCAML_RUNTIME_EVENTS_START environment variable or by 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 it 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. iconic.

The runtime events system's behaviour can be controlled by the following environment variables:

  • -OCAML_RUNTIME_EVENTS_START — the manpage lists this env var with a leading dash; if set, it will cause the runtime events system to be started as part of the OCaml runtime initialization.
  • -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.
  • -OCAML_RUNTIME_EVENTS_PRESERVE — if set, this will prevent the OCaml runtime from removing its ring buffers when it terminates. This can help if you're monitoring very short running programs. lowkey a lifesaver for tiny programs 🫶

🍓 type runtime_counter 🍓

type runtime_counter = — this is 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 occurrence of an event. In the latter case their value will be one. periodt.

  • EV_C_FORCE_MINOR_ALLOC_SMALL — triggering of a minor collection due to a full minor heap. Since 5.0
  • EV_C_FORCE_MINOR_MAKE_VECT — triggering of a minor collection due to Array.make. Since 5.0
  • EV_C_FORCE_MINOR_SET_MINOR_HEAP_SIZE — triggering of a minor collection due to Gc.minor_heap_size. Since 5.0
  • EV_C_FORCE_MINOR_MEMPROF — triggering of a minor collection during memprof young sampling. Since 5.3
  • EV_C_MINOR_PROMOTED — total bytes promoted from the minor heap of this Domain to the major heap in the last minor collection. Since 5.0
  • EV_C_MINOR_ALLOCATED — total bytes allocated in the minor heap of this Domain in the last minor collection. Since 5.0
  • EV_C_REQUEST_MAJOR_ALLOC_SHR — major slice requested due to allocation in major heap. Since 5.0
  • EV_C_REQUEST_MAJOR_ADJUST_GC_SPEED — major slice requested by caml_adjust_gc_speed. Since 5.0
  • EV_C_REQUEST_MINOR_REALLOC_REF_TABLE — triggering of a minor collection due to ref table reallocation. Since 5.0
  • EV_C_REQUEST_MINOR_REALLOC_EPHE_REF_TABLE — triggering of a minor collection due to ephe_ref table reallocation. Since 5.0
  • EV_C_REQUEST_MINOR_REALLOC_CUSTOM_TABLE — triggering of a minor collection due to custom table reallocation. Since 5.0
  • 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. Since 5.1
  • EV_C_MAJOR_HEAP_POOL_LIVE_WORDS — current live words in a Domain's major heap pools. 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. 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. Since 5.1
  • EV_C_MAJOR_HEAP_POOL_LIVE_BLOCKS — live blocks of a Domain's major heap pools. Since 5.1
  • EV_C_MAJOR_HEAP_LARGE_BLOCKS — live blocks of a Domain's major heap large allocations. Since 5.1
  • EV_C_MAJOR_HEAP_WORDS — major heap size in words of a Domain. Since 5.3
  • EV_C_MAJOR_ALLOCATED_WORDS — allocations to the major heap of this Domain in words, since the last major slice. Since 5.3
  • EV_C_MAJOR_ALLOCATED_WORK — the 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. Since 5.3
  • EV_C_MAJOR_DEPENDENT_WORK — the 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. Since 5.3
  • EV_C_MAJOR_EXTRA_WORK — the 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. Since 5.3
  • EV_C_MAJOR_WORK_COUNTER — the global amount of major GC 'work' done by all domains since the program began. Since 5.3
  • EV_C_MAJOR_ALLOC_COUNTER — the global words of major GC allocations done by all domains since the program began. Since 5.3
  • EV_C_MAJOR_SLICE_TARGET — the 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). Since 5.3
  • EV_C_MAJOR_SLICE_BUDGET — the budget in 'work' that a domain has to do during the major slice. Since 5.3
  • EV_C_MINOR_ALLOCATED_WORDS — total words allocated in the minor heap of this Domain in the last minor collection. Since 5.4
  • EV_C_MINOR_PROMOTED_WORDS — total words promoted from the minor heap of this Domain to the major heap in the last minor collection. Since 5.4

🦋 type runtime_phase 🦋

type runtime_phase = — phase events, aka the "what is the runtime doing right now" vibes. here are all the constructors, bestie:

  • EV_EXPLICIT_GC_SET — event spanning a call to Gc.set. Since 5.0
  • EV_EXPLICIT_GC_STAT — event spanning a call to Gc.stat. Since 5.0
  • EV_EXPLICIT_GC_MINOR — event spanning a call to Gc.minor, which forces a minor collection. Since 5.0
  • EV_EXPLICIT_GC_MAJOR — event spanning a call to Gc.major, which forces a major collection. Since 5.0
  • EV_EXPLICIT_GC_FULL_MAJOR — event spanning a call to Gc.full_major, which forces a full major collection. Since 5.0
  • EV_EXPLICIT_GC_COMPACT — event spanning a call to Gc.compact, which triggers a compaction. Since 5.0
  • EV_MAJOR — event spanning any major GC work. Since 5.0
  • EV_MAJOR_SWEEP — event spanning the sweeping work of a major GC. Since 5.0
  • EV_MAJOR_MARK_ROOTS — event spanning the marking of roots in a major GC. Since 5.0
  • EV_MAJOR_MEMPROF_ROOTS — event spanning the marking of memprof roots in a major GC. Since 5.3
  • EV_MAJOR_MARK — event spanning the marking of the heap in a major GC. Since 5.0
  • EV_MINOR — event spanning any minor GC work. Since 5.0
  • EV_MINOR_LOCAL_ROOTS — event spanning the scanning and major allocation of local roots during a minor GC. Since 5.0
  • EV_MINOR_MEMPROF_ROOTS — event spanning the scanning and promotion of memprof roots in a minor GC. Since 5.3
  • EV_MINOR_MEMPROF_CLEAN — event spanning cleaning and updating of memprof structures at the end of a minor GC. Since 5.3
  • EV_MINOR_FINALIZED — event spanning the running of finalisers for dead custom blocks at the end of a minor GC. Since 5.0
  • EV_EXPLICIT_GC_MAJOR_SLICE — event spanning a call to Gc.major_slice. Since 5.0
  • EV_FINALISE_UPDATE_FIRST — event spanning time spent in the first phase of finalisation at the end of a major GC cycle. Since 5.0
  • EV_FINALISE_UPDATE_LAST — event spanning time spent in the last phase of finalisation at the end of a major GC cycle. Since 5.0
  • EV_INTERRUPT_REMOTE — event spanning work triggered by an interrupt from another domain. This is usually a stop-the-world request. Since 5.0
  • EV_MAJOR_EPHE_MARK — event spanning the marking of ephemeron tables in a major GC. Since 5.0
  • EV_MAJOR_EPHE_SWEEP — event spanning the sweeping of ephemeron tables in a major GC. Since 5.0
  • EV_MAJOR_FINISH_MARKING — event spanning work done at the end of marking in a major GC. Since 5.0
  • EV_MAJOR_GC_CYCLE_DOMAINS — event spanning work done at the end of a major GC cycle. This includes a minor collection. Since 5.0
  • EV_MAJOR_GC_PHASE_CHANGE — event spanning the change of phase in the major GC which involves a global barrier. Since 5.0
  • EV_MAJOR_GC_STW — event spanning the stop-the-world phase done at the end of a major GC cycle. Since 5.0
  • EV_MAJOR_MARK_OPPORTUNISTIC — event spanning the work done during opportunistic marking in a major GC. Since 5.0
  • EV_MAJOR_SLICE — event spanning the work done during a major slice in a major GC. Since 5.0
  • EV_MAJOR_FINISH_CYCLE — event spanning attempts to drive all domains to the end of a major GC cycle. Since 5.0
  • EV_MINOR_CLEAR — event spanning the cleaning of the minor heap and supporting structures at the end of a minor GC. Since 5.0
  • EV_MINOR_FINALIZERS_OLDIFY — event spanning the promotion of finalisers during a minor GC. Since 5.0
  • EV_MINOR_GLOBAL_ROOTS — event spanning the scanning and major allocation of global roots during a minor GC. Since 5.0
  • EV_MINOR_LEAVE_BARRIER — event spanning the time spent in the barrier at the end of a minor GC, waiting for all domains to finish their work. Since 5.0
  • EV_STW_API_BARRIER — event spanning the time spent waiting for all other domains to reach the stop-the-world entry barrier. Since 5.0
  • EV_STW_HANDLER — event spanning the time spent in the stop-the-world handler, including time spent in the stop-the-world callback itself.

The span roster is still rolling, and that previous variant’s comment wraps up with Since 5.0 before we hit the next batch. Buckle up, bestie:

  • EV_STW_LEADER — the event spanning the time spent as the leader of a stop-the-world. Since 5.0
  • EV_MAJOR_FINISH_SWEEPING — spans the time spent finishing sweeping when forced to as part of domain termination. Since 5.0
  • EV_MAJOR_MEMPROF_CLEAN — spans the time spent cleaning memprof structures at the end of a major GC. Since 5.3
  • EV_MINOR_FINALIZERS_ADMIN — spans finalisers book-keeping at the end of a minor GC. Since 5.0
  • EV_MINOR_REMEMBERED_SET — spans the scanning and major allocation of remembered sets during a minor GC. Since 5.0
  • EV_MINOR_REMEMBERED_SET_PROMOTE — spans the promotion of blocks in the remembered set and global roots during a minor GC. Since 5.0
  • EV_MINOR_LOCAL_ROOTS_PROMOTE — spans the promotion of local roots during a minor GC. Since 5.0
  • EV_DOMAIN_CONDITION_WAIT — spans waiting in Condition.wait. Since 5.0
  • EV_DOMAIN_RESIZE_HEAP_RESERVATION — spans resizing the domain heap reservation, as a result of minor heap size changes. Since 5.0
  • EV_COMPACT — spans compaction of the heap during a call to Gc.compact. Since 5.2
  • EV_COMPACT_EVACUATE — spans evacuating major GC pools during a compaction. Since 5.2
  • EV_COMPACT_FORWARD — spans the walking of the heap to update changed pointers after an evacuation during a compaction. Since 5.2
  • EV_COMPACT_RELEASE — spans releasing the evacuated pools at the end of a compaction. Since 5.2
  • EV_EMPTY_MINOR — spans a domain needing to empty its minor heap for a new allocation. This includes time spent trying to become stop-the-world leader. Since 5.4

That whole list is the type for span events emitted by the runtime. ✨

Then there’s type lifecycle =, the lifecycle-event roster for Runtime_events and domains:

type lifecycle =
  • EV_RING_START — event indicating that the Runtime_events ring buffer has been started. Includes the PID of the process as an argument. Since 5.0
  • EV_RING_STOP — event indicating that the Runtime_events ring buffer has been stopped. Since 5.0
  • EV_RING_PAUSE — event indicating that the Runtime_events ring buffer has been paused. Since 5.0
  • EV_RING_RESUME — event indicating that the Runtime_events ring buffer has been resumed. Since 5.0
  • EV_FORK_PARENT — event indicating that a fork has occurred and the current domain is the parent. Includes the PID of the child as an argument. Since 5.0
  • EV_FORK_CHILD — event indicating that a fork has occurred and the current domain is the child. Since 5.0
  • EV_DOMAIN_SPAWN — event indicating that a new domain has been spawned. Includes the PID of the new domain as an argument. Since 5.0
  • EV_DOMAIN_TERMINATE — event indicating that a domain has terminated. Includes the PID of the domain as an argument. Since 5.0

Those are the lifecycle events for Runtime_events and domains. 💅

  • val lifecycle_name : lifecycle -> string — returns a string representation of a given lifecycle event type. 🌸
  • val runtime_phase_name : runtime_phase -> string — returns a string representation of a given runtime phase event type. 🌸
  • val runtime_counter_name : runtime_counter -> string — returns a string representation of a given runtime counter type. 🌸
  • type cursor — the type of the cursor used when consuming. 🎀
  • module Timestamp : sig end — yes, it’s literally shaped like that in the source.
  • module Type : sig end — same energy.
  • module User : sig end — same energy.
  • module Callbacks : sig end — same energy.
  • val start : unit -> unit — start () 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. 🔥
  • val path : unit -> string option — if runtime events are being collected, path () returns Some p where p is a path to the runtime events file. Otherwise, it returns None. 🎀
  • val pause : unit -> unit — 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. 💅
  • val resume : unit -> unit — 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 -> cursor — create_cursor path_pid creates a cursor to read from a 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 -> unit — frees a previously created runtime_events cursor. 🧚
  • val read_poll : cursor -> Callbacks.t -> int option -> int — read_poll cursor callbacks max_option calls the corresponding functions on callbacks for up to max_option events read off the cursor’s runtime_events and returns the number of events read. 👑

Source/version: OCamldoc; date: 2026-06-22; footer page: Runtime_events(3). That’s the whole part 2, bestie — go consume those events responsibly 💖🫶

📦 where this page comes from