package b0

  1. Overview
  2. Docs
Software construction and deployment kit

Install 

dune-project
 Dependency

erratique.ch Readme Changelog ISC; BSD-2-Clause License Edit opam file Versions (2)

Authors

  1. T
    The b0 programmers

Maintainers

  1. Daniel Bünzli

Sources

b0-0.0.6.tbz
sha512=e9aa779e66c08fc763019f16d4706f465d16c05d6400b58fbd0313317ef33ddea51952e2b058db28e65f7ddb7012f328c8bf02d8f1da17bb543348541a2587f0

doc/b0.std/B0_std/Log/index.html

Module B0_std.LogSource

Program log.

Examples:

  let () = Log.warn (fun m -> m "The queue is full (%d elements)" count)
  let () = Log.err (fun m -> m "The request timed out after %a" Mtime.pp dur)
  let items =
    Log.time (fun v m -> m "Purged, %d items remaining" (List.length v)) @@
    (fun () -> purge items)

See also the cookbook on logging.

TODO. Think about implicit locations.

Reporting levels

Sourcetype level =
  1. | Quiet
    (*

    Do not report anything.

    *)
  2. | Stdout
    (*

    Outputs to the stdout of the program. Using this allows the output to be silenced when the level is set to Quiet, which may be desirable, or not.

    *)
  3. | Stderr
    (*

    Outputs to the stderr of the program. Using this allows the output to be silenced when the level is set to Quiet, which may be desirable, or not.

    *)
  4. | Error
    (*

    For error conditions that prevent the program from running correctly.

    *)
  5. | Warning
    (*

    For suspicious conditions that do not prevent the program from running normally but may eventually lead to an error condition.

    *)
  6. | Info
    (*

    For conditions that allow the program user to get a better understanding of what the program is doing.

    *)
  7. | Debug
    (*

    For conditions that allow the program developer to get a better understanding of what the program is doing.

    *)

The type for reporting levels.

Sourceval level : unit -> level

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

Sourceval set_level : level -> unit

set_level l sets the reporting level to l.

Use B0_std_cli.set_log_level to set this from the command line.

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.

A message formatting function is called with a message construction function m. The message formatting function must call the given message construction function with an optional header, a format string and its arguments to define the message contents. Here are a few examples of message formatting functions:

  (fun m -> m "%d messages to send" n)
  (fun m -> m ~header:"emails" "%d messages to send" n)

The interpretation of the optional header argument of m is up to the reporter but None should automatically output a header that depend on the log level and Some "" should not output any header, leaving full control of the log formatting to the client.

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

The type for log functions.

Sourceval msg : level -> 'a log

msg level (fun m -> m fmt …) logs with level level a message formatted with fmt. For the semantics of levels see level.

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

kmsg k level (fun m -> m fmt …) logs with level level a message formatted with fmt and continues with k.

Sourceval quiet : 'a log

quiet is msg Quiet.

Sourceval stdout : 'a log

stdout is msg Stdout.

Sourceval stderr : 'a log

stderr is msg Stderr.

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.

Logging result errors

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

if_error ~level ~use r is:

  • v, if r is Ok v
  • use and e is logged using Fmt.lines 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 : 'b Fmt.t -> ?level:level -> ?header:string -> 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' : 'b Fmt.t -> ?level:level -> ?header:string -> use:'a -> ('a, 'b) result -> ('a, 'b) result

if_error_pp' is if_error_pp' wrapped by Result.ok

Logging timings

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 message header with Mtime.Span.pp.

Note. The reporting level is determined after f has been called. This means f can change it to affect the report. See for example b0_std_cookbook.logging_main

Logging values

Sourceval value : ?level:level -> ?id:string -> 'a Fmt.t -> 'a -> 'a

value pp v reports v on level (defaults to Stderr) with pp if id is specified this is of the form "%s: %a" and returns v

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.

Reporting

Sourcemodule Reporter : sig ... end

Reporting.