Module Lwt_log

Logging functions

This module provides logging functions. It is actually a thin extension of Lwt_log_core, adding logging destinations that are only available on Unix and Windows (such as files, standard output, and the system log). Being a thin extension, most of the functions in this module are actually the ones in Lwt_log_core. They are not repeated on this page, however, so please read both Lwt_log_core and this page for a complete understanding.

Here is a simple, self-contained usage example:

let () =
  Lwt_log.default :=
    Lwt_log.channel
      ~template:"$(date).$(milliseconds) [$(level)] $(message)"
      ~close_mode:`Keep
      ~channel:Lwt_io.stdout
      ();

  Lwt_log.add_rule "*" Lwt_log.Info;

  Lwt_main.run begin
    Lwt_log.info "Hello world!"
  end

(* ocamlfind opt -linkpkg -package lwt.unix log_example.ml && ./a.out *)

As an alternative to this module, we suggest trying Logs_lwt from the logs library.

include module type of Lwt_log_core with type Lwt_log_core.level = Lwt_log_core.level and type Lwt_log_core.logger = Lwt_log_core.logger and type Lwt_log_core.section = Lwt_log_core.section and type Lwt_log_core.template = Lwt_log_core.template and module Lwt_log_core.Section = Lwt_log_core.Section
type level = Lwt_log_core.level =
| Debug
| Info
| Notice
| Warning
| Error
| Fatal
type logger = Lwt_log_core.logger
type section = Lwt_log_core.section
val string_of_level : level -> string
val level_of_string : string -> level option
val load_rules : ?⁠fail_on_error:bool -> string -> unit
val add_rule : string -> level -> unit
val append_rule : string -> level -> unit
val reset_rules : unit -> unit
val log : ?⁠exn:exn -> ?⁠section:section -> ?⁠location:(string * int * int) -> ?⁠logger:logger -> level:level -> string -> unit Lwt.t
val log_f : ?⁠exn:exn -> ?⁠section:section -> ?⁠location:(string * int * int) -> ?⁠logger:logger -> level:level -> ('a, unit, string, unit Lwt.t) Stdlib.format4 -> 'a
val ign_log : ?⁠exn:exn -> ?⁠section:section -> ?⁠location:(string * int * int) -> ?⁠logger:logger -> level:level -> string -> unit
val ign_log_f : ?⁠exn:exn -> ?⁠section:section -> ?⁠location:(string * int * int) -> ?⁠logger:logger -> level:level -> ('a, unit, string, unit) Stdlib.format4 -> 'a
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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.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) Stdlib.format4 -> 'a
module Section : sig ... end
type template = Lwt_log_core.template
val render : buffer:Stdlib.Buffer.t -> template:template -> section:section -> level:level -> message:string -> unit
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
val close : logger -> unit Lwt.t
val default : logger Stdlib.ref
val broadcast : logger list -> logger
val dispatch : (section -> level -> logger) -> logger
val null : logger
val render : buffer:Stdlib.Buffer.t -> template:template -> section:section -> level:level -> message:string -> unit

Same as Lwt_log_core.render, except that the template may also contain the following variables:

  • date, which will be replaced with the current local date and time,
  • milliseconds, which will be replaced by the fractional part of the current Unix time, to millisecond accuracy.

For example:

  • "$(date) $(name)[$(pid)]: $(message)"
  • "$(date).$(milliseconds) $(name)[$(pid)]: $(message)"
  • "$(date): $(loc-file): $(loc-line): $(loc-column): $(message)"
type syslog_facility = [
| `Auth
| `Authpriv
| `Cron
| `Daemon
| `FTP
| `Kernel
| `Local0
| `Local1
| `Local2
| `Local3
| `Local4
| `Local5
| `Local6
| `Local7
| `LPR
| `Mail
| `News
| `Syslog
| `User
| `UUCP
| `NTP
| `Security
| `Console
]

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.

parameter paths

is a list of path to try for the syslogd socket. It default to ["/dev/log"; "/var/run/log"].

parameter template

defaults to "$(date) $(name)[$(pid)]: $(section): $(message)"

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

defaults to `Append

parameter template

defaults to "$(date): $(section): $(message)"

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.

parameter template

defaults to "$(name): $(section): $(message)"