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



Types


type level =  | Debug(* Debugging message. They can be automatically removed by the
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 the pattern is omited in a rule then the pattern "*" is used instead, so LWT_LOG may just contains "debug" for instance.

If LWT_LOG is not defined then the rule "* -> notice" is used instead.

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 immediatly and affect all sections for which the level has not been set explicitly with Lwt_log.​Section.​set_level. pattern may contains *. For example:

Lwt_log.add_rule "lwt*" Lwt_log.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.append_rule "*" Lwt_log.Info



Logging functions


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.

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.

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) 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 ->
  ?location:string * int * int ->
  ?logger:logger -> string -> unit Lwt.t
val debug_f : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger ->
  ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a
val info : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger -> string -> unit Lwt.t
val info_f : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger ->
  ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a
val notice : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger -> string -> unit Lwt.t
val notice_f : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger ->
  ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a
val warning : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger -> string -> unit Lwt.t
val warning_f : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger ->
  ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a
val error : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger -> string -> unit Lwt.t
val error_f : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger ->
  ('a, unit, string, unit Lwt.t) Pervasives.format4 -> 'a
val fatal : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?logger:logger -> string -> unit Lwt.t
val fatal_f : 
  ?exn:exn ->
  ?section:section ->
  ?location:string * int * int ->
  ?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