Minidebug_runtime (ppx_minidebug.Minidebug

type time_tagged =

| Not_tagged
| Clock
| Elapsed

type elapsed_times =

| Not_reported
| Seconds
| Milliseconds
| Microseconds
| Nanoseconds

type location_format =

| No_location
| File_only
| Beg_line
| Beg_pos
| Range_line
| Range_pos

type toc_entry_criteria =

| Minimal_depth of int
| Minimal_size of int
| Minimal_span of Mtime.span
| And of toc_entry_criteria list
| Or of toc_entry_criteria list

module type Shared_config = sig ... end

val shared_config : 
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?prefix_all_logs:bool ->
  ?split_files_after:int ->
  ?with_table_of_contents:bool ->
  ?toc_entry:toc_entry_criteria ->
  ?for_append:bool ->
  ?log_level:int ->
  string ->
  (module Shared_config)

Sets up a file with the given path, or if split_files_after is given, creates a directory to store the files. By default the logging will not be time tagged and will be appending to the file / creating more files. If time_tagged is Clock, entries will be tagged with a date and clock time; if it is Elapsed, they will be tagged with the time span elapsed since the start of the process (using Mtime_clock.elapsed). If split_files_after is given and for_append is false, clears the directory. If the opened file exceeds split_files_after characters, Shared_config.refresh_ch () returns true; if in that case Shared_config.debug_ch () is called, it will create and return a new file.

If elapsed_times is different from Not_reported, the elapsed time spans are printed for log subtrees, in the corresponding units with precision up to 1%. The times include printing out logs, therefore might not be reliable for profiling. In the runtime creation functions, elapsed_times defaults to Not_reported.

If print_entry_ids is true, the entry_id identifiers are printed on log headers with the syntax {#ID}; by default they are omitted. If verbose_entry_ids is true, the entry_id identifiers are also printed on logged values.

If global_prefix is given, the log header messages (and the log closing messages for the flushing backend) are prefixed with it.

If prefix_all_logs is true, all logs have the global_prefix prefixed, not just the header messages. Does nothing for the PrintBox (i.e. non-flushing) runtimes.

If table_of_contents_ch is given or with_table_of_contents=true, outputs selected log headers to this channel. The provided file name is used as a prefix for links to anchors of the log headers. Note that debug runtime builders that take a channel instead of a file name, will use global_prefix instead for the anchor links. The setting toc_entry controls the selection of headers to include in a ToC (it defaults to And [], which means including all entries).

log_level, by default 9, specifies Shared_config.init_log_level. This is the initial log level. In particular, the header "BEGIN DEBUG SESSION" is only printed if (initial) log_level > 0.

module type Debug_runtime = sig ... end

When using the ppx_minidebug syntax extension, provide a module called Debug_runtime with this signature in scope of the instrumented code.

module Flushing (_ : Shared_config) : Debug_runtime

The output is flushed line-at-a-time, so no output should be lost if the traced program crashes. The logged traces are still indented, but if the values to print are multi-line, their formatting might be messy. The indentation is also smaller (half of PrintBox).

val default_html_config : PrintBox_html.Config.t

val default_md_config : PrintBox_md.Config.t

type printbox_config = {

mutable hyperlink : [ `Prefix of string | `No_hyperlinks ];
(*
If hyperlink is `Prefix prefix, code pointers are rendered as hyperlinks. When prefix is either empty, starts with a dot, or starts with "http:" or "https:", the link address has the form sprintf "%s#L%d" fname start_lnum, allowing browsing in HTML directly. Otherwise, it has the form sprintf "%s:%d:%d" fname start_lnum (start_colnum + 1), intended for editor-specific prefixes such as "vscode://file/".
Note that rendering a link on a node will make the node non-foldable, therefore it is best to combine `Prefix prefix with values_first_mode=true.
*)
mutable toc_specific_hyperlink : string option;
(*
If provided, overrides hyperlink as the prefix used for generating URIs pointing to anchors in logs.
*)
mutable backend : [ `Text | `Html of PrintBox_html.Config.t | `Markdown of PrintBox_md.Config.t ];
(*
If the content is `Text, logs are generated as monospaced text; for other settings as html or markdown.
*)
mutable boxify_sexp_from_size : int;
(*
If positive, Sexp.t-based logs with this many or more atoms are converted to print-boxes before logging. Disabled by default (i.e. negative).
*)
mutable highlight_terms : Re.re option;
(*
Uses a highlight style for logs on paths ending with a log matching the regular expression.
*)
mutable highlight_diffs : bool;
(*
If true, highlights differences between the current run and the previous run loaded from prev_run_file.
*)
mutable exclude_on_path : Re.re option;
(*
Does not propagate the highlight status from child logs through log headers matching the given regular expression.
*)
mutable prune_upto : int;
(*
At depths lower than prune_upto (or equal if counting from 1) only outputs highlighted boxes. This makes it simpler to trim excessive logging while still providing some context. Defaults to 0 -- no pruning.
*)
mutable truncate_children : int;
(*
If > 0, only the given number of the most recent children is kept at each node. Defaults to 0 -- keep all (no pruning).
*)
mutable values_first_mode : bool;
(*
If set to true, does not put the source code location of a computation as a header of its subtree. Rather, puts the result of the computation as the header of a computation subtree, if rendered as a single line -- or just the name, and puts the result near the top. If false, puts the result at the end of the computation subtree, i.e. preserves the order of the computation.
*)
mutable max_inline_sexp_size : int;
(*
Maximal size (in atoms) up to which a sexp value can be inlined during "boxification".
*)
mutable max_inline_sexp_length : int;
(*
Maximal length (in characters/bytes) up to which a sexp value can be inlined during "boxification".
*)
mutable snapshot_every_sec : float option;
(*
If given, output a snapshot of the pending logs when at least the given time (in seconds) has passed since the previous output. This is only checked at calls to log values.
*)
mutable sexp_unescape_strings : bool;
(*
If true, when a value is a sexp atom or is decomposed into a sexp atom by boxification, it is not printed as a sexp, but the string of the atom is printed directly. Defaults to true.
*)
mutable with_toc_listing : bool;
(*
If true, outputs non-collapsed trees of ToC entries in the Table of Contents files.
*)
mutable toc_flame_graph : bool;
(*
If true, outputs a minimalistic rendering of a flame graph in the Table of Contents files, with boxes positioned to reflect both the ToC entries hierarchy and elapsed times for the opening and closing of entries. Not supported in the `Text backend.
*)
mutable flame_graph_separation : int;
(*
How many pixels a single box, for a log header, is expected to take in a flame graph. Defaults to 40. Note: ideally the height of a flame tree should be calculated automatically, then this setting would disappear.
*)
mutable prev_run_file : string option;
(*
If provided, enables highlighting differences between the current run and the previous run loaded from this file.
*)

}

module type PrintBox_runtime = sig ... end

module PrintBox (_ : Shared_config) : PrintBox_runtime

The logged traces will be pretty-printed as trees using the `printbox` package. This logger supports conditionally disabling a particular nesting of the logs, regardless of where in the nesting level no_debug_if is called.

val debug_file : 
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?split_files_after:int ->
  ?with_toc_listing:bool ->
  ?toc_entry:toc_entry_criteria ->
  ?toc_flame_graph:bool ->
  ?flame_graph_separation:int ->
  ?highlight_terms:Re.t ->
  ?exclude_on_path:Re.t ->
  ?prune_upto:int ->
  ?truncate_children:int ->
  ?for_append:bool ->
  ?boxify_sexp_from_size:int ->
  ?max_inline_sexp_length:int ->
  ?backend:
    [ `Text
    | `Html of PrintBox_html.Config.t
    | `Markdown of PrintBox_md.Config.t ] ->
  ?hyperlink:string ->
  ?toc_specific_hyperlink:string ->
  ?values_first_mode:bool ->
  ?log_level:int ->
  ?snapshot_every_sec:float ->
  ?prev_run_file:string ->
  ?diff_ignore_pattern:Re.t ->
  ?max_distance_factor:int ->
  ?entry_id_pairs:(int * int) list ->
  string ->
  (module PrintBox_runtime)

Creates a PrintBox-based debug runtime configured to output html or markdown to a file with the given name suffixed with ".log", ".html" or ".md" depending on the backend. By default the logging will not be time tagged and the file will be created or erased by this function (unless for_append=true). The default boxify_sexp_from_size value is 50.

Setting ~with_toc_listing:true or ~toc_flame_graph:true or both will create an additional log file, the given name suffixed with "-toc" and the corresponding file name extension. This file will collect selected entries, hyperlinking to anchors in the main logging file(s).

If prev_run_file is provided, differences between the current run and the previous run will be highlighted in the output. The diff_ignore_pattern parameter can be used to specify a regular expression pattern that will be removed from messages before comparison, allowing certain differences to be ignored. The max_distance_factor parameter (default 50) controls how far to search around a center row when computing edit distances between runs - higher values may find more matches but will be slower.

If entry_id_pairs is provided, the diffing algorithm will force matches between specific entry IDs from the previous run and the current run. Each pair (prev_id, curr_id) indicates that entry prev_id from the previous run should be matched with entry curr_id from the current run. This is useful for ensuring specific debug entries are compared even if their positions change significantly.

By default backend is `Text. See printbox_config for details about PrintBox-specific parameters. See shared_config for the details about shared parameters.

val debug : 
  ?debug_ch:Stdlib.out_channel ->
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?table_of_contents_ch:Stdlib.out_channel ->
  ?toc_entry:toc_entry_criteria ->
  ?boxify_sexp_from_size:int ->
  ?max_inline_sexp_length:int ->
  ?backend:
    [ `Text
    | `Html of PrintBox_html.Config.t
    | `Markdown of PrintBox_md.Config.t ] ->
  ?hyperlink:string ->
  ?toc_specific_hyperlink:string ->
  ?highlight_terms:Re.t ->
  ?exclude_on_path:Re.t ->
  ?prune_upto:int ->
  ?truncate_children:int ->
  ?values_first_mode:bool ->
  ?log_level:int ->
  ?snapshot_every_sec:float ->
  unit ->
  (module PrintBox_runtime)

Same as debug_file, but by default it will log to stdout and will not be time tagged, and some functionality is not supported.

See printbox_config for details about PrintBox-specific parameters. See shared_config for the details about shared parameters.

val debug_flushing : 
  ?debug_ch:Stdlib.out_channel ->
  ?table_of_contents_ch:Stdlib.out_channel ->
  ?filename:string ->
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?prefix_all_logs:bool ->
  ?split_files_after:int ->
  ?with_table_of_contents:bool ->
  ?toc_entry:toc_entry_criteria ->
  ?for_append:bool ->
  ?log_level:int ->
  unit ->
  (module Debug_runtime)

Creates a flushing-based debug runtime. By default it will log to stdout and will not be time tagged. At most one of debug_ch, filename can be provided. Adds the suffix ".log" to the file name if filename is given.

See shared_config for the details about shared parameters.

val forget_printbox : (module PrintBox_runtime) -> (module Debug_runtime)

Upcasts the runtime.

val sexp_of_lazy_t : ('a -> Sexplib0.Sexp.t) -> 'a lazy_t -> Sexplib0.Sexp.t

Unlike Lazy.sexp_of_t available in the Base library, does not force the lazy value, only converts it if it's already computed and non-exception.

val local_runtime : 
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?split_files_after:int ->
  ?with_toc_listing:bool ->
  ?toc_entry:toc_entry_criteria ->
  ?toc_flame_graph:bool ->
  ?flame_graph_separation:int ->
  ?highlight_terms:Re.t ->
  ?exclude_on_path:Re.t ->
  ?prune_upto:int ->
  ?truncate_children:int ->
  ?for_append:bool ->
  ?boxify_sexp_from_size:int ->
  ?max_inline_sexp_length:int ->
  ?backend:
    [ `Text
    | `Html of PrintBox_html.Config.t
    | `Markdown of PrintBox_md.Config.t ] ->
  ?hyperlink:string ->
  ?toc_specific_hyperlink:string ->
  ?values_first_mode:bool ->
  ?log_level:int ->
  ?snapshot_every_sec:float ->
  ?prev_run_file:string ->
  ?diff_ignore_pattern:Re.t ->
  ?max_distance_factor:int ->
  ?entry_id_pairs:(int * int) list ->
  ?update_config:(printbox_config -> unit) ->
  string ->
  unit ->
  (module Debug_runtime)

A wrapper around debug_file, the local_runtime ... filename_stem callback returns a thread-local runtime, where a thread's log file is named filename_stem-thread_id.ext (where ext is ".log", ".html", or ".md"). The runtime can be re-configured during each retrieval using update_config if provided.

val local_runtime_flushing : 
  ?table_of_contents_ch:Stdlib.out_channel ->
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?split_files_after:int ->
  ?with_table_of_contents:bool ->
  ?toc_entry:toc_entry_criteria ->
  ?for_append:bool ->
  ?log_level:int ->
  string ->
  unit ->
  (module Debug_runtime)

A wrapper around debug_flushing, the local_runtime_flushing ... filename_stem callback returns a thread-local runtime, where a thread's log file is named filename_stem-thread_id.log.

val prefixed_runtime : 
  ?debug_ch:Stdlib.out_channel ->
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?table_of_contents_ch:Stdlib.out_channel ->
  ?toc_entry:toc_entry_criteria ->
  ?highlight_terms:Re.t ->
  ?exclude_on_path:Re.t ->
  ?prune_upto:int ->
  ?truncate_children:int ->
  ?values_first_mode:bool ->
  ?boxify_sexp_from_size:int ->
  ?max_inline_sexp_length:int ->
  ?backend:
    [ `Text
    | `Html of PrintBox_html.Config.t
    | `Markdown of PrintBox_md.Config.t ] ->
  ?hyperlink:string ->
  ?toc_specific_hyperlink:string ->
  ?log_level:int ->
  ?snapshot_every_sec:float ->
  ?update_config:(printbox_config -> unit) ->
  unit ->
  unit ->
  (module Debug_runtime)

A wrapper around debug, the prefixed_runtime ... ?global_prefix ... () callback returns a thread-local runtime that prefixes all log messages with the given global_prefix concatenated with the thread ID (if non-zero). If global_prefix is not provided, the prefix will default to "Thread-<thread ID>" if the thread ID is non-zero, or an empty string otherwise.

See printbox_config for details about PrintBox-specific parameters. See shared_config for the details about shared parameters.

val prefixed_runtime_flushing : 
  ?debug_ch:Stdlib.out_channel ->
  ?table_of_contents_ch:Stdlib.out_channel ->
  ?time_tagged:time_tagged ->
  ?elapsed_times:elapsed_times ->
  ?location_format:location_format ->
  ?print_entry_ids:bool ->
  ?verbose_entry_ids:bool ->
  ?global_prefix:string ->
  ?split_files_after:int ->
  ?with_table_of_contents:bool ->
  ?toc_entry:toc_entry_criteria ->
  ?for_append:bool ->
  ?log_level:int ->
  unit ->
  unit ->
  (module Debug_runtime)

A wrapper around debug_flushing, following the same pattern as prefixed_runtime.

See shared_config for the details about shared parameters.