module Lwt_log:sig
..end
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
logger
Lwt provides loggers sending log messages to a file, syslog,
... but you can also create you own logger.
type
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
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
stringval ign_log : ?exn:exn ->
?section:section ->
?location:string * int * int ->
?logger:logger -> level:level -> string -> unit
Lwt_log.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) Pervasives.format4 -> 'a
Lwt_log.log_f
but ignore the resulting thread.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 ign_debug : ?exn:exn ->
?section:section ->
?location:string * int * int -> ?logger:logger -> string -> unit
val ign_debug_f : ?exn:exn ->
?section:section ->
?location:string * int * int ->
?logger:logger -> ('a, unit, string, unit) 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 ign_info : ?exn:exn ->
?section:section ->
?location:string * int * int -> ?logger:logger -> string -> unit
val ign_info_f : ?exn:exn ->
?section:section ->
?location:string * int * int ->
?logger:logger -> ('a, unit, string, unit) 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 ign_notice : ?exn:exn ->
?section:section ->
?location:string * int * int -> ?logger:logger -> string -> unit
val ign_notice_f : ?exn:exn ->
?section:section ->
?location:string * int * int ->
?logger:logger -> ('a, unit, string, unit) 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 ign_warning : ?exn:exn ->
?section:section ->
?location:string * int * int -> ?logger:logger -> string -> unit
val ign_warning_f : ?exn:exn ->
?section:section ->
?location:string * int * int ->
?logger:logger -> ('a, unit, string, unit) 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 ign_error : ?exn:exn ->
?section:section ->
?location:string * int * int -> ?logger:logger -> string -> unit
val ign_error_f : ?exn:exn ->
?section:section ->
?location:string * int * int ->
?logger:logger -> ('a, unit, string, unit) 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
val ign_fatal : ?exn:exn ->
?section:section ->
?location:string * int * int -> ?logger:logger -> string -> unit
val ign_fatal_f : ?exn:exn ->
?section:section ->
?location:string * int * int ->
?logger:logger -> ('a, unit, string, unit) Pervasives.format4 -> 'a
module Section:sig
..end
typetemplate =
string
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 datemilliseconds
which will be replaced by the fractionnal part
of the current unix timename
which will be replaced by the program namepid
which will be replaced by the pid of the programmessage
which will be replaced by the message emitedlevel
which will be replaced by a string representation of
the levelsection
which will be replaced by the name of the
message's sectionloc-file
which will be replaced by the file name of the
calling logging functionloc-line
which will be replaced by the line number of the
calling logging functionloc-column
which will be replaced by the column number of
the calling logging function"$(name): $(message)"
"$(date) $(name)[$(pid)]: $(message)"
"$(date).$(milliseconds) $(name)[$(pid)]: $(message)"
"$(date): $(loc-file): $(loc-line): $(loc-column): $(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
. The location is obtained from threads local
storage.val location_key : (string * int * int) Lwt.key
exception Logger_closed
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
val default : logger Pervasives.ref
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)
val null : logger
typesyslog_facility =
[ `Auth
| `Authpriv
| `Console
| `Cron
| `Daemon
| `FTP
| `Kernel
| `LPR
| `Local0
| `Local1
| `Local2
| `Local3
| `Local4
| `Local5
| `Local6
| `Local7
| `NTP
| `News
| `Security
| `Syslog
| `UUCP
| `User ]
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
.
mode = `Truncate
then the file is truncated and previous
contents will be lost.mode = `Append
, new messages will be appended at the end
of the filetemplate
: 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)"