Library
Module
Module type
Parameter
Class
Class type
Logging facility
This module provides functions to deal with logging. It support:
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
| 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 of a logger. A logger is responsible for dispatching messages and storing them somewhere.
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 contents of the LWT_LOG
environment variable, which must contain 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 contain "debug"
for instance.
By default, the following rule apply : "* -> notice"
val string_of_level : level -> string
val level_of_string : string -> level option
Reset the rules set when parsing the LWT_LOG
environment variable using this string.
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 immediately and affects all sections for which the level has not been set explicitly with Section.set_level
. pattern
may contains *
. For example:
Lwt_log_core.add_rule "lwt*" Lwt_log_core.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_core.append_rule "*" Lwt_log_core.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 Section.main
. If logger
is not specified, then the default one is used instead (see 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) format4 ->
'a
log_f
is the same as log
except that it takes a format string
val ign_log :
?exn:exn ->
?section:section ->
?location:(string * int * int) ->
?logger:logger ->
level:level ->
string ->
unit
Same as 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) format4 ->
'a
Same as log_f
but ignore the resulting thread.
The following functions are the same as log
except that their name determines which level is used.
For example info
msg
is the same as log
~level:Info msg
.
module Section : sig ... end
Sections
A template is for generating log messages.
It is a string which may contains variables of the form $(var)
, where var
is one of:
message
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 functionFor example:
"$(name): $(message)"
"$(name): $(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
The key for storing current location.
val make :
output:(section -> level -> string list -> unit Lwt.t) ->
close:(unit -> unit Lwt.t) ->
logger
make ~output ~close
creates a new logger.
The default logger. It is used as default when no one is specified. If Lwt_core
is linked (in the package lwt.unix
) the default logger sends all messages to standard error. Otherwise the default logger is null
.
broadcast loggers
is a logger which send messages to all the given loggers.
Note: closing a broadcast logger does not close its components.
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_core.dispatch
(fun section level ->
match Lwt_log_core.Section.name section, level with
| "access", _ -> access_logger
| _, Lwt_log_core.Error -> error_logger)
val null : logger
Logger which drops everything