package async_unix

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

A library for general logging.

Although this module is fully Async-safe it exposes almost no Deferreds. This is partially a design choice to minimize the impact of logging in code, and partially the result of organic design (i.e., older versions of this interface did the same thing).

A (limited) Blocking module is supplied to accommodate the portion of a program that runs outside of Async.

module Level : sig ... end
module Message : sig ... end
module Rotation : sig ... end
module Output : sig ... end
module Blocking : sig ... end

Async programs often have a non-Async portion that runs before the scheduler begins to capture command line options, do setup, read configs, etc. This module provides limited global logging functions to be used during that period. Calling these functions after the scheduler has started will raise an exception. They otherwise behave similarly to the logging functions in the Async world.

type t
val sexp_of_t : t -> Sexplib0.Sexp.t
module type Global_intf = sig ... end

An interface for singleton logs.

This functor can be called to generate "singleton" logging modules.

Programs that want simplistic single-channel logging can open this module. It provides a global logging facility to a single output type at a single level. More nuanced logging can be had by using the functions that operate on a distinct Log.t type.

val set_level_via_param : t -> unit Core.Command.Param.t

Sets the log level via a flag, if provided.

val set_level : t -> Level.t -> unit

Messages sent at a level less than the current level will not be output.

val level : t -> Level.t

Returns the last level passed to set_level, which will be the log level checked as a threshold against the level of the next message sent.

val set_output : t -> Output.t list -> unit

Changes the output type of the log, which can be useful when daemonizing. The new output type will be applied to all subsequent messages.

val get_output : t -> Output.t list
val get_time_source : t -> Async_kernel.Synchronous_time_source.t

Changes the time source of the log, which controls the default timestamp on messages.

val set_time_source : t -> Async_kernel.Synchronous_time_source.t -> unit
val get_transform : t -> (Message.t -> Message.t) option

Changes the transform function within log. This allows you to *synchronously* change things about the message at the time that they were written.

The transform function *will not* be called if the initial message is of a level that would not currently be logged.

The transform function *will* be called if even if there are no log outputs.

val set_transform : t -> (Message.t -> Message.t) option -> unit
val get_on_error : t -> [ `Raise | `Call of Core.Error.t -> unit ]

If `Raise is given, then background errors raised by logging will be raised to the monitor that was in scope when create was called. Errors can be redirected anywhere by providing `Call f.

val set_on_error : t -> [ `Raise | `Call of Core.Error.t -> unit ] -> unit
val close : t -> unit Async_kernel.Deferred.t

Any call that writes to a log after close is called will raise.

val is_closed : t -> bool

Returns true if close has been called.

val flushed : t -> unit Async_kernel.Deferred.t

Returns a Deferred.t that is fulfilled when the last message delivered to t before the call to flushed is out the door.

val rotate : t -> unit Async_kernel.Deferred.t

Informs the current Outputs to rotate if possible.

val create : level:Level.t -> output:Output.t list -> on_error:[ `Raise | `Call of Core.Error.t -> unit ] -> ?time_source:Async_kernel.Synchronous_time_source.t -> ?transform:(Message.t -> Message.t) -> unit -> t

Creates a new log. See set_level, set_on_error, set_output, set_time_source, and set_transform for more.

val copy : t -> t

Creates a copy of a log, which has the same settings and logs to the same outputs.

Printf-like logging for messages at each log level or raw (no level) messages. Raw messages still include a timestamp.

val raw : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> ('a, unit, string, unit) Core.format4 -> 'a
val debug : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> ('a, unit, string, unit) Core.format4 -> 'a
val info : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> ('a, unit, string, unit) Core.format4 -> 'a
val error : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> ('a, unit, string, unit) Core.format4 -> 'a
val printf : ?level:Level.t -> ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> ('a, unit, string, unit) Core.format4 -> 'a

Generalized printf-style logging.

Sexp logging for messages at each log level or raw (no level) messages. Raw messages still include a timestamp

val raw_s : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> Core.Sexp.t -> unit
val info_s : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> Core.Sexp.t -> unit
val error_s : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> Core.Sexp.t -> unit
val debug_s : ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> Core.Sexp.t -> unit
val sexp : ?level:Level.t -> ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> Core.Sexp.t -> unit

Generalized sexp-style logging.

val string : ?level:Level.t -> ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> string -> unit

Log a string directly.

val message : t -> Message.t -> unit

Log a pre-created message.

val surround_s : on_subsequent_errors:[ `Call of exn -> unit | `Log | `Raise ] -> ?level:Level.t -> ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> Core.Sexp.t -> (unit -> 'a Async_kernel.Deferred.t) -> 'a Async_kernel.Deferred.t

surround t message f logs message and a UUID once before calling f and again after f returns or raises. If f raises, the second message will include the exception, and surround itself will re-raise the exception tagged with message. on_subsequent_errors is passed to the internal monitor as rest argument. As usual, the logging happens only if level exceeds the minimum level of t.

val surroundf : on_subsequent_errors:[ `Call of exn -> unit | `Log | `Raise ] -> ?level:Level.t -> ?time:Time_float_unix.t -> ?tags:(string * string) list -> t -> ('a, unit, string, (unit -> 'b Async_kernel.Deferred.t) -> 'b Async_kernel.Deferred.t) Core.format4 -> 'a
val would_log : t -> Level.t option -> bool

would_log returns true if a message at the given log level would be logged if sent immediately.

This will return false if there are no outputs for the log, unless there is a transform set.

module Reader : sig ... end
module For_testing : sig ... end
OCaml

Innovation. Community. Security.