1Runtime_events(3) OCaml library Runtime_events(3)
2
6 Runtime_events - Runtime events - ring buffer-based runtime tracing
7
9 Module Runtime_events
10
12 Module Runtime_events
13 : sig end
14 Runtime events - ring buffer-based runtime tracing
17 This module enables users to enable and subscribe to tracing events
19 from the Garbage Collector and other parts of the OCaml runtime. This
20 can be useful for diagnostic or performance monitoring purposes. This
21 module can be used to subscribe to events for the current process or
22 external processes asynchronously.
23 When enabled (either via setting the OCAML_RUNTIME_EVENTS_START envi‐
25 ronment variable or calling Runtime_events.start) a file with the pid
26 of the process and extension .events will be created. By default this
27 is in the current directory but can be over-ridden by the OCAML_RUN‐
28 TIME_EVENTS_DIR environment variable. Each domain maintains its own
29 ring buffer in a section of the larger file into which it emits events.
30 There is additionally a set of C APIs in runtime_events.h that can en‐
32 able zero-impact monitoring of the current process or bindings for
33 other languages.
34 The runtime events system's behaviour can be controlled by the follow‐
36 ing environment variables:
37 -OCAML_RUNTIME_EVENTS_START if set will cause the runtime events system
40 to be started as part of the OCaml runtime initialization.
41 -OCAML_RUNTIME_EVENTS_DIR sets the directory where the runtime events
44 ring buffers will be located. If not present the program's working di‐
45 rectory will be used.
46 -OCAML_RUNTIME_EVENTS_PRESERVE if set will prevent the OCaml runtime
49 from removing its ring buffers when it terminates. This can help if
50 monitoring very short running programs.
51 type runtime_counter =
58 | EV_C_FORCE_MINOR_ALLOC_SMALL
59 | EV_C_FORCE_MINOR_MAKE_VECT
60 | EV_C_FORCE_MINOR_SET_MINOR_HEAP_SIZE
61 | EV_C_FORCE_MINOR_MEMPROF
62 | EV_C_MINOR_PROMOTED
63 | EV_C_MINOR_ALLOCATED
64 | EV_C_REQUEST_MAJOR_ALLOC_SHR
65 | EV_C_REQUEST_MAJOR_ADJUST_GC_SPEED
66 | EV_C_REQUEST_MINOR_REALLOC_REF_TABLE
67 | EV_C_REQUEST_MINOR_REALLOC_EPHE_REF_TABLE
68 | EV_C_REQUEST_MINOR_REALLOC_CUSTOM_TABLE
69 The type for counter events emitted by the runtime
72 type runtime_phase =
75 | EV_EXPLICIT_GC_SET
76 | EV_EXPLICIT_GC_STAT
77 | EV_EXPLICIT_GC_MINOR
78 | EV_EXPLICIT_GC_MAJOR
79 | EV_EXPLICIT_GC_FULL_MAJOR
80 | EV_EXPLICIT_GC_COMPACT
81 | EV_MAJOR
82 | EV_MAJOR_SWEEP
83 | EV_MAJOR_MARK_ROOTS
84 | EV_MAJOR_MARK
85 | EV_MINOR
86 | EV_MINOR_LOCAL_ROOTS
87 | EV_MINOR_FINALIZED
88 | EV_EXPLICIT_GC_MAJOR_SLICE
89 | EV_FINALISE_UPDATE_FIRST
90 | EV_FINALISE_UPDATE_LAST
91 | EV_INTERRUPT_REMOTE
92 | EV_MAJOR_EPHE_MARK
93 | EV_MAJOR_EPHE_SWEEP
94 | EV_MAJOR_FINISH_MARKING
95 | EV_MAJOR_GC_CYCLE_DOMAINS
96 | EV_MAJOR_GC_PHASE_CHANGE
97 | EV_MAJOR_GC_STW
98 | EV_MAJOR_MARK_OPPORTUNISTIC
99 | EV_MAJOR_SLICE
100 | EV_MAJOR_FINISH_CYCLE
101 | EV_MINOR_CLEAR
102 | EV_MINOR_FINALIZERS_OLDIFY
103 | EV_MINOR_GLOBAL_ROOTS
104 | EV_MINOR_LEAVE_BARRIER
105 | EV_STW_API_BARRIER
106 | EV_STW_HANDLER
107 | EV_STW_LEADER
108 | EV_MAJOR_FINISH_SWEEPING
109 | EV_MINOR_FINALIZERS_ADMIN
110 | EV_MINOR_REMEMBERED_SET
111 | EV_MINOR_REMEMBERED_SET_PROMOTE
112 | EV_MINOR_LOCAL_ROOTS_PROMOTE
113 | EV_DOMAIN_CONDITION_WAIT
114 | EV_DOMAIN_RESIZE_HEAP_RESERVATION
115 The type for span events emitted by the runtime
118 type lifecycle =
121 | EV_RING_START
122 | EV_RING_STOP
123 | EV_RING_PAUSE
124 | EV_RING_RESUME
125 | EV_FORK_PARENT
126 | EV_FORK_CHILD
127 | EV_DOMAIN_SPAWN
128 | EV_DOMAIN_TERMINATE
129 Lifecycle events for the ring itself
132 val lifecycle_name : lifecycle -> string
136 Return a string representation of a given lifecycle event type
138 val runtime_phase_name : runtime_phase -> string
142 Return a string representation of a given runtime phase event type
144 val runtime_counter_name : runtime_counter -> string
148 Return a string representation of a given runtime counter type
150 type cursor
153 Type of the cursor used when consuming
156 module Timestamp : sig end
159 module Callbacks : sig end
164 val start : unit -> unit
170 start () will start the collection of events in the runtime if not al‐
173 ready started.
174 Events can be consumed by creating a cursor with create_cursor and pro‐
176 viding a set of callbacks to be called for each type of event.
177 val pause : unit -> unit
181 pause () will pause the collection of events in the runtime. Traces
184 are collected if the program has called Runtime_events.start () or the
185 OCAML_RUNTIME_EVENTS_START environment variable has been set.
186 val resume : unit -> unit
190 resume () will resume the collection of events in the runtime. Traces
193 are collected if the program has called Runtime_events.start () or the
194 OCAML_RUNTIME_EVENTS_START environment variable has been set.
195 val create_cursor : (string * int) option -> cursor
199 create_cursor path_pid creates a cursor to read from an runtime_events.
202 Cursors can be created for runtime_events in and out of process. A run‐
203 time_events ring-buffer may have multiple cursors reading from it at
204 any point in time and a program may have multiple cursors open concur‐
205 rently (for example if multiple consumers want different sets of
206 events). If path_pid is None then a cursor is created for the current
207 process. Otherwise the pair contains a string path to the directory
208 that contains the pid .events file and int pid for the runtime_events
209 of an external process to monitor.
210 val free_cursor : cursor -> unit
214 Free a previously created runtime_events cursor
216 val read_poll : cursor -> Callbacks.t -> int option -> int
220 read_poll cursor callbacks max_option calls the corresponding functions
223 on callbacks for up to max_option events read off cursor 's run‐
224 time_events and returns the number of events read.
225OCamldoc 2023-07-20 Runtime_events(3)