Module Logs


Logs provides a basic logging infrastructure. Logging is performed on sources whose reporting level can be set independently. Log message report is decoupled from logging and handled by a reporter.

See the basics, a few usage conventions to respect and a note on synchronous logging.

v0.7.0 - homepage

Reporting levels

type level =
| App
| Error
| Warning
| Info
| Debug

The type for reporting levels. For level semantics see the usage conventions.

Log sources have an optional reporting level. If the level is Some l then any message whose level is smaller or equal to l is reported. If the level is None no message is ever reported.

val level : unit -> level option

level () is the reporting level given to new sources.

val set_level : ?⁠all:bool -> level option -> unit

set_level ?all l sets the reporting level given to new sources. If all is true (default), also sets the reporting level of all existing sources. Use Src.set_level to only affect a specific source. Only applications should use this function directly see usage conventions.

val pp_level : Stdlib.Format.formatter -> level -> unit

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

val level_to_string : level option -> string

level_to_string l converts l to an US-ASCII string that can be parsed back by level_of_string and by the LEVEL option argument of Logs_cli.level.

val level_of_string : string -> (level option[ `Msg of string ]) Stdlib.result

level_of_string s parses the representation of level_to_string from s.

Log sources

type src

The type for log sources. A source defines a named unit of logging whose reporting level can be set independently.

val default : src

default is a logging source that is reserved for use by applications. See usage conventions.

module Src : sig ... end


Log functions

module Tag : sig ... end

Message tags.

type ('a, 'b) msgf = (?⁠header:string -> ?⁠tags:Tag.set -> ('aStdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a) -> 'b

The type for client specified message formatting functions.

Message formatting functions are called with a message construction function whenever a message needs to be reported. The message formatting function must call the given message construction function with a format string and its arguments to define the message contents, see the basics for examples. The optional arguments of the message construction function are:

  • header, an optional printable message header. Default to None.
  • tags, a set of tags to attach to the message. Defaults Tag.empty.
type 'a log = ('a, unit) msgf -> unit

The type for log functions. See the basics to understand how to use log functions.

val msg : ?⁠src:src -> level -> 'a log

msg ?src l (fun m -> m fmt ...) logs with level l on the source src (defaults to default) a message formatted with fmt. For the semantics of levels see the the usage conventions.

val app : ?⁠src:src -> 'a log

app is msg App.

val err : ?⁠src:src -> 'a log

err is msg Error.

val warn : ?⁠src:src -> 'a log

warn is msg Warning.

val info : ?⁠src:src -> 'a log

info is msg Info.

val debug : ?⁠src:src -> 'a log

debug is msg Debug.

val kmsg : (unit -> 'b) -> ?⁠src:src -> level -> ('a'b) msgf -> 'b

kmsg k is like msg but calls k for returning.

Logging result value Errors

val on_error : ?⁠src:src -> ?⁠level:level -> ?⁠header:string -> ?⁠tags:Tag.set -> pp:(Stdlib.Format.formatter -> 'b -> unit) -> use:('b -> 'a) -> ('a'b) Stdlib.result -> 'a

on_error ~level ~pp ~use r is:

  • v if r = Ok v
  • use e if r = Error e. As a side effect msg is logged with pp on level level (defaults to Logs.level.Error).
val on_error_msg : ?⁠src:src -> ?⁠level:level -> ?⁠header:string -> ?⁠tags:Tag.set -> use:(unit -> 'a) -> ('a[ `Msg of string ]) Stdlib.result -> 'a

on_error_msg is like on_error but uses Format.pp_print_text to format the message.

Source specific log functions

module type LOG = sig ... end

The type for source specific logging functions.

val src_log : src -> (module LOG)

src_log src is a set of logging functions for src.


type reporter = {
report : a b. src -> level -> over:(unit -> unit) -> (unit -> 'b) -> ('a'b) msgf -> 'b;

The type for reporters.

A reporter formats and handles log messages that get reported. Whenever a log function gets called on a source with a level equal or smaller to the source's reporting level, the current reporter's field gets called as src level ~over k msgf where:

  • src is the logging source.
  • level is the reporting level.
  • over must be called by the reporter once the logging operation is over from the reporter's perspective. This may happen before or after k is called.
  • k is the function to invoke to return.
  • msgf is the message formatting function to call.

See an example.

val nop_reporter : reporter

nop_reporter is the initial reporter returned by reporter, it does nothing if a log message gets reported.

val format_reporter : ?⁠pp_header:(Stdlib.Format.formatter -> (level * string option) -> unit) -> ?⁠app:Stdlib.Format.formatter -> ?⁠dst:Stdlib.Format.formatter -> unit -> reporter

format_reporter ~pp_header ~app ~dst () is a reporter that reports App level messages on app (defauts to Format.std_formatter) and all other level on dst (defaults to Format.err_formatter).

pp_header determines how message headers are rendered. The default prefixes the program name and renders the header with pp_header. Use Logs_fmt:reporter if you want colored headers rendering.

The reporter does not process or render information about message sources or tags.

Important. This is a synchronous reporter it considers the log operation to be over once the message was formatted and before calling the continuation (see the note on synchronous logging). In particular if the formatters are backed by channels, it will block until the message has been formatted on the channel before proceeding which may not be suitable in a cooperative concurrency setting like Lwt.

val reporter : unit -> reporter

reporter () is the current repporter.

val set_reporter : reporter -> unit

set_reporter r sets the current reporter to r.

val set_reporter_mutex : lock:(unit -> unit) -> unlock:(unit -> unit) -> unit

set_reporter_mutex ~lock ~unlock sets the mutex primitives used to access the reporter. lock is called before invoking the reporter and unlock after it returns. Initially both lock and unlock are fun () -> ().

val pp_header : Stdlib.Format.formatter -> (level * string option) -> unit

pp_header ppf (l, h) prints an unspecified representation of log header h for level l.

Logs monitoring

val err_count : unit -> int

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

val warn_count : unit -> int

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



Reporter setup

Usage conventions

Note on synchronous logging

Example with custom reporter and tags

Logging to multiple reporters