Module Lwt_log


module Lwt_log: sig .. end
Logging facility


This module provides functions to deal with logging. It support:



Types


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
Sections

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:

For example:
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.

Loggers

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

        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 = [ `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
desf_file ?template ?mode ?perm ~file_name () creates an logger which will write messages to file_name.


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