package b0

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

Module B0_std.LogSource

Program log.

Support for program logging. Not to be used by build logic.

The module is modelled after Logs logging, see this quick introduction. It can be made to log on a Logs source, see here.

FIXME This should maybe moved to B00_ui. Make the doc self contained (cf. references to Logs). OTOH it's nice to simply open B0_std and be done.

Reporting levels

Sourcetype level =
  1. | Quiet
  2. | App
  3. | Error
  4. | Warning
  5. | Info
  6. | Debug

The type for reporting levels. They are meant to be used as follows:

  • Quiet doesn't report anything.
  • App can be used for the standard output or console of an application. Using this instead of stdout directly allows the output to be silenced by Quiet which may be desirable, or not.
  • Error is an error condition that prevents the program from running.
  • Warning is a suspicious condition that does not prevent the program from running normally but may eventually lead to an error condition.
  • Info is a condition that allows the program user to get a better understanding of what the program is doing.
  • Debug is a condition that allows the program developer to get a better understanding of what the program is doing.
Sourceval level : unit -> level

level () is the current reporting level. The initial level is set to Warning.

Sourceval set_level : level -> unit

set_level l sets the current reporting level to l.

Sourceval pp_level : level Fmt.t

pp_level ppf l prints and unspecified representation of l on ppf.

Sourceval level_to_string : level -> string

level_to_string l converts l to a string representation.

Sourceval level_of_string : string -> (level, string) result

level_of_string s parses a level from s according to the representation of level_to_string.

Log functions

Sourcetype ('a, 'b) msgf = (?header:string -> ('a, Format.formatter, unit, 'b) format4 -> 'a) -> 'b

The type for client specified message formatting functions. See Logs.msgf.

header interpretation is up to the reported but None should automatially output headers that depend on the level and Some "" should not output any header leaving full control to the client.

Sourcetype 'a log = ('a, unit) msgf -> unit

The type for log functions. See Logs.log.

Sourceval msg : level -> 'a log

See Logs.msg.

Sourceval quiet : 'a log

quiet is msg Quiet.

Sourceval app : 'a log

app is msg App.

Sourceval err : 'a log

err is msg Error.

Sourceval warn : 'a log

warn is msg Warning.

Sourceval info : 'a log

info is msg Info.

Sourceval debug : 'a log

debug is msg Debug.

Sourceval kmsg : (unit -> 'b) -> level -> ('a, 'b) msgf -> 'b

kmsg k level m logs m with level level and continues with k.

Logging result value Error messages

Sourceval if_error : ?level:level -> ?header:string -> use:'a -> ('a, string) result -> 'a

if_error ~level ~use v r is:

  • v, if r is Ok v
  • use and e is logged with level (defaults to Error), if r is Error e.
Sourceval if_error' : ?level:level -> ?header:string -> use:'a -> ('a, string) result -> ('a, 'b) result

if_error' is if_error wrapped by Result.ok.

Sourceval if_error_pp : ?level:level -> ?header:string -> 'b Fmt.t -> use:'a -> ('a, 'b) result -> 'a

if_error_pp ~level pp ~use r is

  • v, if r is Ok v.
  • use and e is logged with level (defaults to Error) using pp, if r is Error e.
Sourceval if_error_pp' : ?level:level -> ?header:string -> 'b Fmt.t -> use:'a -> ('a, 'b) result -> ('a, 'b) result

if_error_pp' is if_error_pp' wrapped by Result.ok

Timings logging

Sourceval time : ?level:level -> ('a -> (('b, Format.formatter, unit, 'a) format4 -> 'b) -> 'a) -> (unit -> 'a) -> 'a

time ~level m f logs m with level level (defaults to Info) and the time f () took as the log header.

Note. The current log level is determined after f has been called this means f can change it to affect the log operation. This allows f to be the main function of your program and let it set the log level.

Spawn logging

Sourceval spawn_tracer : level -> Os.Cmd.spawn_tracer

spawn_tracer level is a spawn tracer that logs with level level. If level is Log.level.Quiet this is B0_std.Os.Cmd.spawn_tracer_nop.

Log monitoring

Sourceval err_count : unit -> int

err_count () is the number of messages logged with level Error.

Sourceval warn_count : unit -> int

warn_count () is the number of messages logged with level Warning.

Logger

The following function allows to change the logging backend. Note that in this case monitoring and level functions are no longer relevant.

Sourcetype kmsg = {
  1. kmsg : 'a 'b. (unit -> 'b) -> level -> ('a, 'b) msgf -> 'b;
}

The type for the basic logging function. The function is never invoked with a level of Quiet.

Sourceval kmsg_nop : kmsg

nop_kmsg is a logger that does nothing.

Sourceval kmsg_default : kmsg

kmsg_default is the default logger that logs messages on Fmt.stderr except for Log.level.App level which logs on Fmt.stdout.

Sourceval set_kmsg : kmsg -> unit

set_kmsg kmsg sets the logging function to kmsg.