Skip to content

Commit

Permalink
Clarify doc for global compile time setting, prepare for release 2.0.1
Browse files Browse the repository at this point in the history
  • Loading branch information
lukstafi committed Sep 8, 2024
1 parent 7b7a692 commit 3018ea6
Show file tree
Hide file tree
Showing 4 changed files with 10 additions and 6 deletions.
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -449,7 +449,7 @@ The `%diagn_` extension points (short for "diagnostic") are tailored for the "lo
In the `PrintBox` backend, logs accumulate until the current toplevel log scope is closed. This is unfortunate in the logging framework context, where promptly informing the user using the logs might be important. To remedy this, `PrintBox_runtime` offers the setting `snapshot_every_sec`. When set, if sufficient time has passed since the last output, the backend will output the whole current toplevel log scope. If possible, the previous snapshot of the same log scope is erased, to not duplicate information. The underlying mechanism is available as [snapshot] in the generic interface; it does nothing in the flushing backend. [snapshot] is useful when there's a risk of a "premature" exit of the debugged program or thread.
The log levels are integers intended to be within the range 0-9, where 0 means no logging at all. They can be provided explicitly by all extension entry points and all explicit logging extensions. When omitted, the log level of the enclosing log entry is used; the default for a top-level log entry is log level 1. The syntax for logging at a compile-time given level is by example: `%debug2_sexp` (log at level 2), `%log3` (log at level 3), `%log1_resut` (log result at level 1), `%diagn3_sexp` (log at level 3) etc.
The log levels are integers intended to be within the range 0-9, where 0 means no logging at all. They can be provided explicitly by all extension entry points and all explicit logging extensions. When omitted, the log level of the enclosing log entry is used; the default for a top-level log entry is log level 1 (unless the compile-time log level is set globally). The syntax for logging at a compile-time given level is by example: `%debug2_sexp` (log at level 2), `%log3` (log at level 3), `%log1_resut` (log result at level 1), `%diagn3_sexp` (log at level 3) etc.
The `%diagn_` extension points further restrict logging to explicit logs only. Example from the test suite:
Expand All @@ -462,7 +462,7 @@ The `%diagn_` extension points further restrict logging to explicit logs only. E
(b - 3) * y
in
let () = print_endline @@ Int.to_string @@ bar { first = 7; second = 42 } in
let baz { first : int; second : int } : int =
let%diagn_show baz { first : int; second : int } : int =
let { first : int; second : int } = { first = first + 1; second = second + 3 } in
[%log "for baz, f squared", (first * first : int)];
(first * first) + second
Expand Down Expand Up @@ -536,6 +536,8 @@ There's also a way to compile the code adaptively, using a shell environment var
The generated code will check that the compile-time adaptive pruning matches the runtime value of the environment variable. If that's an obstacle, use `%%global_debug_log_level_from_env_var_unsafe` which will not perform the check. Using `%%global_debug_log_level_from_env_var_unsafe` is very prone to workflow bugs where different parts of a codebase are compiled with different log levels, leading to confusing behavior.
Important: when the compile-time log level is set by `%%global_log_level` or `%%global_debug_log_level_from_env_var`, this becomes the default for top-level log entries without an explicit log level!
Another example from the test suite, notice how the log level of `%log1` overrides the parent log level of `%debug3_show`:
```ocaml
Expand Down
2 changes: 1 addition & 1 deletion dune-project
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@

(documentation https://lukstafi.github.io/ppx_minidebug/ppx_minidebug)

(version 2.0.0)
(version 2.0.1)

(package
(name ppx_minidebug)
Expand Down
6 changes: 4 additions & 2 deletions index.mld
Original file line number Diff line number Diff line change
Expand Up @@ -455,7 +455,7 @@ The [%diagn_] extension points (short for "diagnostic") are tailored for the "lo

In the [PrintBox] backend, logs accumulate until the current toplevel log scope is closed. This is unfortunate in the logging framework context, where promptly informing the user using the logs might be important. To remedy this, [PrintBox_runtime] offers the setting [snapshot_every_sec]. When set, if sufficient time has passed since the last output, the backend will output the whole current toplevel log scope. If possible, the previous snapshot of the same log scope is erased, to not duplicate information. The underlying mechanism is available as \[snapshot\] in the generic interface; it does nothing in the flushing backend. \[snapshot\] is useful when there's a risk of a "premature" exit of the debugged program or thread.

The log levels are integers intended to be within the range 0-9, where 0 means no logging at all. They can be provided explicitly by all extension entry points and all explicit logging extensions. When omitted, the log level of the enclosing log entry is used; the default for a top-level log entry is log level 1. The syntax for logging at a compile-time given level is by example: [%debug2_sexp] (log at level 2), [%log3] (log at level 3), [%log1_resut] (log result at level 1), [%diagn3_sexp] (log at level 3) etc.
The log levels are integers intended to be within the range 0-9, where 0 means no logging at all. They can be provided explicitly by all extension entry points and all explicit logging extensions. When omitted, the log level of the enclosing log entry is used; the default for a top-level log entry is log level 1 (unless the compile-time log level is set globally). The syntax for logging at a compile-time given level is by example: [%debug2_sexp] (log at level 2), [%log3] (log at level 3), [%log1_resut] (log result at level 1), [%diagn3_sexp] (log at level 3) etc.

The [%diagn_] extension points further restrict logging to explicit logs only. Example from the test suite:

Expand All @@ -468,7 +468,7 @@ The [%diagn_] extension points further restrict logging to explicit logs only. E
(b - 3) * y
in
let () = print_endline @@ Int.to_string @@ bar { first = 7; second = 42 } in
let baz { first : int; second : int } : int =
let%diagn_show baz { first : int; second : int } : int =
let { first : int; second : int } = { first = first + 1; second = second + 3 } in
[%log "for baz, f squared", (first * first : int)];
(first * first) + second
Expand Down Expand Up @@ -542,6 +542,8 @@ There's also a way to compile the code adaptively, using a shell environment var

The generated code will check that the compile-time adaptive pruning matches the runtime value of the environment variable. If that's an obstacle, use [%%global_debug_log_level_from_env_var_unsafe] which will not perform the check. Using [%%global_debug_log_level_from_env_var_unsafe] is very prone to workflow bugs where different parts of a codebase are compiled with different log levels, leading to confusing behavior.

Important: when the compile-time log level is set by [%%global_log_level] or [%%global_debug_log_level_from_env_var], this becomes the default for top-level log entries without an explicit log level!

Another example from the test suite, notice how the log level of [%log1] overrides the parent log level of [%debug3_show]:

{@ocaml[
Expand Down
2 changes: 1 addition & 1 deletion ppx_minidebug.opam
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# This file is generated by dune, edit dune-project instead
opam-version: "2.0"
version: "2.0.0"
version: "2.0.1"
synopsis: "Debug logs for selected functions and let-bindings"
description:
"Formatted logs of let-bound values, function arguments and results; `if` and `match` branches taken. Optionally, as collapsible HTML trees with highlights."
Expand Down

0 comments on commit 3018ea6

Please sign in to comment.