Module Lwt_log

module Lwt_log: sig..end

Logging facility

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 message

type logger

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.

type 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 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 used instead.

Logging functions

val log :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger -> level:level -> string -> unit Lwt.t

log ?section ?logger ~level message logs a message.

section defaults to Lwt_log.​Section.​main. If logger is not specified, then the default one is used instead (see Lwt_log.​default).

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.

val log_f :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger ->
    level:level ->
    ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

log_f is the same as log except that it takes a format string

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.

val debug :
   ?exn:exn ->
    ?section:section -> ?logger:logger -> string -> unit Lwt.t

val debug_f :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger ->
    ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val info :
   ?exn:exn ->
    ?section:section -> ?logger:logger -> string -> unit Lwt.t

val info_f :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger ->
    ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val notice :
   ?exn:exn ->
    ?section:section -> ?logger:logger -> string -> unit Lwt.t

val notice_f :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger ->
    ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val warning :
   ?exn:exn ->
    ?section:section -> ?logger:logger -> string -> unit Lwt.t

val warning_f :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger ->
    ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val error :
   ?exn:exn ->
    ?section:section -> ?logger:logger -> string -> unit Lwt.t

val error_f :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger ->
    ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

val fatal :
   ?exn:exn ->
    ?section:section -> ?logger:logger -> string -> unit Lwt.t

val fatal_f :
   ?exn:exn ->
    ?section:section ->
    ?logger:logger ->
    ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a

module Section: sig..end


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)"

val render :
   buffer:Buffer.t ->
    template:template ->
    section:section -> level:level -> message:string -> unit

render ~buffer ~template ~section ~level ~message instantiate all variables of template, and store the result in buffer.


exception Logger_closed

Exception raised when trying to use a closed logger

val make :
   output:(section -> level -> string list -> unit Lwt.t) ->
    close:(unit -> unit Lwt.t) -> 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

val close : logger -> unit Lwt.t

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.

val broadcast : logger list -> logger

broadcast loggers is a logger which send messages to all the given loggers.

Note: closing a broadcast logger does not close its components.

val dispatch : (section -> level -> logger) -> logger

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

          (fun section level ->
            match section, level with
              | "access", _ -> access_logger
              | _, Lwt_log.Error -> error_logger)

Predefined loggers

val null : logger

Logger which drops everything

type syslog_facility =
   [ `Auth
    | `Authpriv
    | `Console
    | `Cron
    | `Daemon
    | `FTP
    | `Kernel
    | `LPR
    | `Local0
    | `Local1
    | `Local2
    | `Local3
    | `Local4
    | `Local5
    | `Local6
    | `Local7
    | `Mail
    | `NTP
    | `News
    | `Security
    | `Syslog
    | `UUCP
    | `User ]

Syslog facility. Look at the SYSLOG(3) man page for a description of syslog facilities

val syslog :
   ?template:template ->
    ?paths:string list ->
    facility:syslog_facility -> unit -> logger

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"].

val file :
   ?template:template ->
    ?mode:[ `Append | `Truncate ] ->
    ?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 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

val channel :
   ?template:template ->
    close_mode:[ `Close | `Keep ] ->
    channel:Lwt_io.output_channel -> unit -> logger

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)"