This module provides logging functions. It is actually a thin extension of
Lwt_log_core, adding logging destinations that are only available on Unix and Windows (such as files, standard output, and the system log). Being a thin extension, most of the functions in this module are actually the ones in
Lwt_log_core. They are not repeated on this page, however, so please read both
Lwt_log_core and this page for a complete understanding.
Here is a simple, self-contained usage example:
let () = Lwt_log.default := Lwt_log.channel ~template:"$(date).$(milliseconds) [$(level)] $(message)" ~close_mode:`Keep ~channel:Lwt_io.stdout (); Lwt_log.add_rule "*" Lwt_log.Info; Lwt_main.run begin Lwt_log.info "Hello world!" end (* ocamlfind opt -linkpkg -package lwt.unix log_example.ml && ./a.out *)
include module type of Lwt_log_core
with type level = Lwt_log_core.level
and type logger = Lwt_log_core.logger
and type section = Lwt_log_core.section
and type template = Lwt_log_core.template
and module Section = Lwt_log_core.Section
This module provides functions to deal with logging. It support:
- logging to multiple destination at the same time
- filtering logs per destination
type level = Lwt_log_core.level =
Debugging message. They can be automatically removed by the syntax extension.*)
Informational message. Suitable to be displayed when the program is in verbose mode.*)
Info, but is displayed by default.
Something strange happend*)
An error message, which should not means the end of the program.*)
A fatal error happened, in most cases the program will end after a fatal error.*)
Type of log levels. A level determines the importance of a message
type logger = Lwt_log_core.logger
Type of a logger. A logger is responsible for dispatching messages and storing them somewhere.
type section = Lwt_log_core.section
Each logging message has a section. Sections can be used to structure your logs. For example you can choose different loggers according to the section.
Each section carries a level, and messages with a lower log level than than the section level will be dropped.
Section levels are initialised using the contents of the
LWT_LOG environment variable, which must contain one or more rules of the form
pattern -> level separated by ";". Where
pattern is a string that may contain
For example, if
access -> warning; foo[*] -> error
If the pattern is omited in a rule then the pattern
"*" is used instead, so
LWT_LOG may just contain
"debug" for instance.
By default, the following rule apply :
"* -> notice"
val string_of_level : level -> string
val level_of_string : string -> level option
Reset the rules set when parsing the
LWT_LOG environment variable using this string.
val add_rule : string -> level -> unit
add_rule pattern level adds a rule for sections logging levels. The rule is added before all other rules. It takes effect immediately and affects all sections for which the level has not been set explicitly with
pattern may contains
*. For example:
Lwt_log_core.add_rule "lwt*" Lwt_log_core.Info
val append_rule : string -> level -> unit
append_rule pattern level adds the given rule after all other rules. For example to set the default fallback rule:
Lwt_log_core.append_rule "*" Lwt_log_core.Info
val log : ?exn:exn -> ?section:section -> ?location:(string * int * int) -> ?logger:logger -> level:level -> string -> unit Lwt.t
log ?section ?logger ~level message logs a message.
exn is provided, then its string representation (=
Printexc.to_string exn) will be append to the message, and if possible the backtrace will also be logged.
location contains the location of the logging directive, it is of the form
(file_name, line, column).
val log_f : ?exn:exn -> ?section:section -> ?location:(string * int * int) -> ?logger:logger -> level:level -> ('a, unit, string, unit Lwt.t) format4 -> 'a
log_f is the same as
log except that it takes a format string
val ign_log : ?exn:exn -> ?section:section -> ?location:(string * int * int) -> ?logger:logger -> level:level -> string -> unit
log but ignore the resulting thread.
val ign_log_f : ?exn:exn -> ?section:section -> ?location:(string * int * int) -> ?logger:logger -> level:level -> ('a, unit, string, unit) format4 -> 'a
log_f but ignore the resulting thread.
The following functions are the same as
log except that their name determines which level is used.
module Section = Lwt_log_core.Section
type template = Lwt_log_core.template
A template is for generating log messages.
It is a string which may contains variables of the form
var is one of:
messagewhich will be replaced by the message emited
levelwhich will be replaced by a string representation of the level
sectionwhich will be replaced by the name of the message's section
loc-filewhich will be replaced by the file name of the calling logging function
loc-linewhich will be replaced by the line number of the calling logging function
loc-columnwhich will be replaced by the column number of the calling logging function
"$(name): $(loc-file): $(loc-line): $(loc-column): $(message)"
val location_key : (string * int * int) Lwt.key
The key for storing current location.
val make : output:(section -> level -> string list -> unit Lwt.t) -> close:(unit -> unit Lwt.t) -> logger
make ~output ~close creates a new logger.
The default logger. It is used as default when no one is specified. If
Lwt_core is linked (in the package
lwt.unix) the default logger sends all messages to standard error. Otherwise the default logger is
broadcast loggers is a logger which send messages to all the given loggers.
Note: closing a broadcast logger does not close its components.
dispatch f is a logger which dispatch logging instructions to different logger according to their level and/or section.
Here is an example:
let access_logger = Lwt_log.file "access.log" and error_logger = Lwt_log.file "error.log" in Lwt_log_core.dispatch (fun section level -> match Lwt_log_core.Section.name section, level with | "access", _ -> access_logger | _, Lwt_log_core.Error -> error_logger)
val null : logger
Logger which drops everything
val render : buffer:Buffer.t -> template:template -> section:section -> level:level -> message:string -> unit
Lwt_log_core.render, except that the template may also contain the following variables:
date, which will be replaced with the current local date and time,
milliseconds, which will be replaced by the fractional part of the current Unix time, to millisecond accuracy.
"$(date) $(name)[$(pid)]: $(message)"
"$(date).$(milliseconds) $(name)[$(pid)]: $(message)"
"$(date): $(loc-file): $(loc-line): $(loc-column): $(message)"
type syslog_facility = [
Syslog facility. Look at the SYSLOG(3) man page for a description of syslog facilities
syslog ?template ?paths ~facility () creates an logger which send message to the system logger.
val file : ?template:template -> ?mode:[ `Truncate | `Append ] -> ?perm:Unix.file_perm -> file_name:string -> unit -> logger Lwt.t
desf_file ?template ?mode ?perm ~file_name () creates an logger which will write messages to
mode = `Truncatethen the file is truncated and previous contents will be lost.
mode = `Append, new messages will be appended at the end of the file