package landmarks

  1. Overview
  2. Docs
package landmarks
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module LandmarkSource

Sourcemodule Graph : sig ... end

All about exporting profiling results

The main module

Sourceval clock : unit -> Int64.t

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

Sourceexception LandmarkFailure of string

Landmarks

Landmarks identify portions of code, they are registered with the function register and delimited by enter and exit.

Sourcetype landmark

The type of landmarks.

Sourceval register : ?id:string -> ?location:string -> string -> landmark

register name registers a new landmark. Note that landmarks are identified by location + name (or by id if provided). If you register a landmark twice the second call returns a physically equal value to the first call (if you provide id the name & location of the second call is ignored).

Sourceval landmark_of_id : string -> landmark option

landmark_of_id id return the landmark currently identify by id.

Sourceval enter : landmark -> unit

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

Sourceval exit : landmark -> unit

Ends a landmark block.

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

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

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

Puts landmark blocks around a function without catching exceptions.

Counter and samplers

Counters are similar to landmarks except they represent empty pieces of code. Their only primitive is increment which adds a constant to the field calls. Samplers are used to collect floats.

Sourcetype counter

The type of counters.

Sourceval register_counter : string -> counter

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

Sourceval increment : ?times:int -> counter -> unit

Increments the number of calls attached to the counter.

Sourcetype sampler

The type of samplers.

Sourceval register_sampler : string -> sampler

register_counter name registers a new sampler.

Sourceval sample : sampler -> float -> unit

Collects a float.

Manage profiling

Sourceval profiling : unit -> bool

Checks if the profiling is ongoing.

Sourcetype profile_output =
  1. | Silent
    (*

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

    *)
  2. | Temporary of string option
    (*

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

    *)
  3. | Channel of out_channel
    (*

    writes in the results in out_channel.

    *)

Where to output results.

Sourcetype textual_option = {
  1. threshold : float;
}
Sourcetype profile_format =
  1. | JSON
    (*

    Easily parsable export format.

    *)
  2. | 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.

Sourcetype profiling_options = {
  1. debug : bool;
    (*

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

    *)
  2. allocated_bytes : bool;
    (*

    Also collect Gc.allocated_bytes during profiling.

    *)
  3. sys_time : bool;
    (*

    Also collect Sys.time timestamps during profiling.

    *)
  4. 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).

    *)
  5. output : profile_output;
    (*

    Specify where to output the results.

    *)
  6. format : profile_format;
    (*

    Specify the output format.

    *)
}

The profiling options control the behavior of the landmark infrastructure.

Sourceval default_options : profiling_options

The default profiling_options.

Sourceval set_profiling_options : profiling_options -> unit

Sets the options.

Sourceval profiling_options : unit -> profiling_options

Get the options.

Sourceval start_profiling : ?profiling_options:profiling_options -> unit -> unit

Starts the profiling.

Sourceval stop_profiling : unit -> unit

Stops the profiling.

Sourceval reset : unit -> unit

Reset the profiling information gathered by the current process.

Sourceval export : ?label:string -> unit -> Graph.graph

Export the profiling information of the current process.

Sourceval export_and_reset : ?label:string -> unit -> Graph.graph

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

Sourceval 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.

Sourceval push_profiling_state : unit -> unit

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

Sourceval pop_profiling_state : unit -> unit

See push_profiling_state ().

Sourceval raise : exn -> 'a

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