module Lwt_log: sig..end
This module provides functions to deal with logging. It support:
- logging to the syslog daemon
- logging to a channel (stderr, stdout, ...)
- logging to a file
- logging to multiple destination at the same time
type level =
||||Debug||(*||Debugging message. They can be automatically removed byt hte syntax extension.||*)|
||||Info||(*||Informational message. Suitable to be displayed when the program is in verbose mode.||*)|
||||Notice||(*||Same as Info, but is displayed by default.||*)|
||||Warning||(*||Something strange happend||*)|
||||Error||(*||An error message, which should not means the end of the program.||*)|
||||Fatal||(*||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
Type of a logger. A logger is responsible for dispatching messages
and storing them somewhere.
Lwt provides loggers sending log messages to a file, syslog,
... but you can also create you own logger.
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 LWT_LOG environment
variable, which must contains one or more rules of the form
pattern -> level separated by ";". Where pattern is a string
that may contain *.
For example, if LWT_LOG contains:
access -> warning; foo[*] -> error
then the level of the section "access" is Warning and the
level of any section matching "foo[*]" is Error.
If LWT_LOG is not defined then the rule "* -> notice" is
Logging functions ¶
log ?section ?logger ~level message logs a message.
If 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.
log_f is the same as log except that it takes a format
The following functions are the same as Lwt_log.log except that their name determines which level is used.
For example info msg is the same as log ~level:Info msg.
Log templates ¶
type template = string
A template is for generating log messages.
It is a string which may contains variables of the form
$(var), where var is one of:
- date which will be replaced with the current date
- milliseconds which will be replaced by the fractionnal part of the current unix time
- name which will be replaced by the program name
- pid which will be replaced by the pid of the program
- message which will be replaced by the message emited
- level which will be replaced by a string representation of the level
- section which will be replaced by the name of the message's section
For example:* "$(name): $(message)"
- "$(date) $(name)[$(pid)]: $(message)"
- "$(date).$(milliseconds) $(name)[$(pid)]: $(message)"
render ~buffer ~template ~section ~level ~message instantiate
all variables of template, and store the result in
Exception raised when trying to use a closed logger
make ~output ~close creates a new logger.
output : is used to write logs. It is a function which receive a section, a level and a list lines that must be logged together.
close : is used to close the logger
Close the given logger
val default : logger Pervasives.ref
The default logger. It is used as default when no one is
specified. Initially, it sends messages to the standard output
for error messages.
broadcast loggers is a logger which send messages to all the
Note: closing a broadcast logger does not close its
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.dispatch (fun section level -> match Lwt_log.Section.name section, level with | "access", _ -> access_logger | _, Lwt_log.Error -> error_logger)
Predefined loggers ¶
val null : logger
Logger which drops everything
type syslog_facility =
| `User ]
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.
template : defaults to "$(date) $(name)[$(pid)]: $(section): $(message)"
paths : is a list of path to try for the syslogd socket. It default to ["/dev/log"; "/var/run/log"].
desf_file ?template ?mode ?perm ~file_name () creates an
logger which will write messages to file_name.
- if mode = `Truncate then the file is truncated and previous contents will be lost.
- if mode = `Append, new messages will be appended at the end of the file
template : defaults to "$(date): $(section): $(message)"
mode : defaults to `Append
channel ?template ~close_mode ~channel () creates a logger
from a channel.
If close_mode = `Close then channel is closed when the
logger is closed, otherwise it is left open.
template : defaults to "$(name): $(section): $(message)"