Module Landmark

module Graph : sig ... end

All about exporting profiling results

external clock : unit -> Stdlib.Int64.t = "caml_highres_clock"

This function is used by the landmark infrastructure to measure the number of cycles inside landmarks.

exception LandmarkFailure of string

Landmarks

type landmark

The type of landmarks.

val register : ?⁠location:string -> string -> landmark

register name registers a new landmark. Should always be called at top-level.

val enter : landmark -> unit

Begins a landmark block. /!\ Landmark blocks should be well-nested, otherwise a failure will be raised during profiling.

val exit : landmark -> unit

Ends a landmark block.

val wrap : landmark -> ('a -> 'b) -> 'a -> 'b

Puts landmark blocks around a function (and close the block and re-raise in case of uncaught exception).

val unsafe_wrap : landmark -> ('a -> 'b) -> 'a -> 'b

Puts landmark blocks around a function without catching exceptions.

Counter and samplers

type counter

The type of counters.

val register_counter : string -> counter

register_counter name registers a new counter. Should always be called at top-level.

val increment : ?⁠times:int -> counter -> unit

Increments the number of calls attached to the counter.

type sampler

The type of samplers.

val register_sampler : string -> sampler

register_counter name registers a new sampler.

val sample : sampler -> float -> unit

Collects a float.

Manage profiling

val profiling : unit -> bool

Checks if the profiling is ongoing.

type profile_output =
| Silent

Disables the automatic output of profiling results when the program ends.

| Temporary of string option

Writes the results in a temporary files and prints its path on stderr.

| Channel of Stdlib.out_channel

Writes in the results in out_channel.

Where to output results.

type textual_option = {
threshold : float;
}
type profile_format =
| JSON

Easily parsable export format.

| Textual of textual_option

Console friendly output; nodes below the threshold (0.0 <= threshold <= 100.0) are not displayed in the callgraph.

The output format for the results.

type profiling_options = {
debug : bool;

Activates a verbose mode that outputs traces on stderr each time the landmarks primitives are called. Default: false.

allocated_bytes : bool;

Also collect Gc.allocated_bytes during profiling.

sys_time : bool;

Also collect Sys.time timestamps during profiling.

recursive : bool;

When false, the recursive instances of landmarks (entering a landmark that has already been entered) are ignored (the number of calls is updated but it does not generate a new node in the callgraph).

output : profile_output;

Specify where to output the results.

format : profile_format;

Specify the output format.

}

The profiling options control the behavior of the landmark infrastructure.

val default_options : profiling_options

The default profiling_options.

val set_profiling_options : profiling_options -> unit

Sets the options.

val profiling_options : unit -> profiling_options

Get the options.

val start_profiling : ?⁠profiling_options:profiling_options -> unit -> unit

Starts the profiling.

val stop_profiling : unit -> unit

Stops the profiling.

val reset : unit -> unit

Reset the profiling information gathered by the current process.

val export : ?⁠label:string -> unit -> Graph.graph

Export the profiling information of the current process.

val export_and_reset : ?⁠label:string -> unit -> Graph.graph

Export the profiling information of the current process; then reset internal state.

val merge : Graph.graph -> unit

Aggregate the profiling information (exported by another process) to the current one. This should is used by the master process to merge exported profiles of workers.

val push_profiling_state : unit -> unit

Save the state of the profiler on a stack to be retrieved later by pop_profiling_state ().

val pop_profiling_state : unit -> unit

See push_profiling_state ().

external raise : exn -> 'a = "%raise"

This a redefinition of Stdlib.raise to allow generated code to work with -no-stdlib.