core_profiler

Profiling library
IN THIS PACKAGE
val is_enabled : bool

is_enabled can be used to "guard" expensive computations done while recording a metric. For example:

Probe.record len <some computation>

If <some computation> is just a variable reference it is free (when using Core_profiler_disabled). However, if it involves some actual work, it is better to write:

if Profiler.is_enabled then Probe.record len <some computation>

When using online or offline profiling, the boolean is constant true and with disabled profiling, the boolean is false.

val configure : ?don't_require_core_profiler_env:unit -> ?offline_profiler_data_file:string -> ?online_print_time_interval_secs:int -> ?online_print_by_default:bool -> unit -> unit

configure lets one set various profiler parameters programmatically.

  • don't_require_core_profiler_env : To protect against Core_profiler being enabled in production, it will check the environment variable CORE_PROFILER whenever you try to create the first Timer or Probe. Setting don't_require_core_profiler_env disables raising an exception if the CORE_PROFILER environment variable is not set.

You need to call this before any Timer or Probe has been created. If you set don't_require_core_profiler_env after a Timer or Probe has been created, then it will raise an exception if the value you are trying to set disagrees with that which was read from the environment.

  • offline_profiler_data_file : This specifies the name of the data file to use. By default this is "profiler.dat".
  • online_print_time_interval_secs : This is the rate at which stats should be printed by the online profiler. Stats may not be printed at this rate is one does not call at or safe_to_delay periodically.
  • online_print_by_default : Setting this to false disables printing stats every time interval. One can print stats by explicitly calling dump_stats.

The environment variable CORE_PROFILER can be used to configure the app. Also see core_profiler_env_help_string below.

val safe_to_delay : unit -> unit

There are several slow operations that may happen occasionally when calling record: allocation, Time_stamp_counter calibration, etc. safe_to_delay checks if they will be necessary soon, and does them in advance. If possible, call this (fairly regularly) from a time-insensitive point in code (or at least, outside any deltas / groups) to reduce the number of spurious jumps in time deltas. If you know for certain that you will be using Core_profiler, you also probably want to call this at startup, to perform the first allocation.

val dump_stats : unit -> unit

In the online profiler, dump_stats prints a table of stats -- this is the same table that is printed periodically and this function gives the user the option to disable the automatic printing and take control of the printing process.

In the offline profiler, dump_stats writes out all the collected stats so far. This normally happens at_exit and this function lets the programmer dump the stats earlier.