mirage-logs 2.1.0 · OCaml Package

Log Thresholds

type threshold = [ `All | `Src of string ] * Logs.level option

threshold type is used to control logging level and source.

The first element of the pair is a source pattern. It can be either `All (representing all the existing and new sources) or `Src src, representing the specific logging source named src.

The second element is the logging level. A log level of None indicates that logging is disabled for this source. If the level is Some l then any message whose level is smaller or equal to l is reported.

val env : Cmdliner.Cmd.Env.info

env is the environment variable LOGGING_LEVELS.

val levels : 
  ?env:Cmdliner.Cmd.Env.info ->
  ?docs:string ->
  unit ->
  threshold list Cmdliner.Term.t

levels ~docs ~env () is a term that processes command-line arguments and environment variables to produce a list of thresholds for logging.

docs is the title of the man page section in which the argument will be listed. env defines the name of an environment variable which is looked up for defining the argument if it is absent from the command line (default is logging_levels_env). See the description of docs and env in the Cmdliner manual for more details.

The option work as follow:

The parameters is split into groups on ','
each group is turned into a threshold but splitting it on ':'
the expected logging levels are "app", "error", "warning", "info" and "debug". The are translated into the equivalent Some d value.
To disable a source, use "quiet" or "-" to get a None value.

For instance, --logging-level '*:info,foo:debug,bar:-' is evaluated as follows.

"*:info" is (`All, Some Logs.Info);
"foo:debug" is (`Src "foo", Some Logs.debug); and
"bar:-" is (`Src "bar", None)

This means: use the default logging threshold Logs.Info for all sources, apart from the source "foo" that should use Logs.Debug and the source "bar" that should be disabled.

val set_levels : default:Logs.level option -> threshold list -> unit

set_levels ~default l configures the logging system to use all the log sources that appear in the threshold list l. If a log source is not present in l, then the default logging level is applied.

If the default level is Some l then any message sent to a source not in l and whose level is smaller or equal to l is reported. If the default level is None no message other than the ones in l are ever reported.

val setup : unit Cmdliner.Term.t

setup is a term that the init the logging system using set_levels. It parses the command-line arguments with levels and Logs_cli.setup_log.

package mirage-logs

Log Thresholds