Module Vlt.OutputSource

This module defines the concept of output, that is how an event is written to a channel. It is possible to register new outputs through the register function. Initially, two outputs are registered:

Definitions
Sourceclass type impl = object ... end

The type of output objects, that is concrete implementation.

Sourcetype rotation = {
  1. seconds_elapsed : float option;
    (*

    Number of seconds between two rotations.

    *)
  2. signal_caught : Signal.t option;
    (*

    Number of signal provoking a rotation.

    *)
}

The type of rotation conditions, rotation occurring when one of the conditions is met.

Sourcetype t = string -> rotation -> Layout.t lazy_t -> impl

The type of outputs, that is a function constructing an actual output implementation. The first parameter describes the output (e. g. filename), while the second one is an optional rotation value (e. g. time between two file switches). The exact semantics associated with both parameters is output-dependent. The third argument is the layout associated with the logger, it is needed to get header and footer (that can be necessary because some outputs may want to write them at each rotation.)

Sourceval register : string -> t -> unit

register n o registers the output o with name n, replacing any existing output with the same name.

Sourceval register_unnamed : t -> string

Similar to register except that an unused name is generated and returned.

Sourceval get : string -> t

get n returns the output registered with name n.

Raises Not_found if no output exists with the passed name.

Predefined outputs
Sourceval void : t

The output initially registered with the name "void". Discards all data; all three parameters being ignored.

Sourceval file : t

The output initially registered with the name "file". Uses bare files, writing header and footer at each rotation (if any). The rotation is given by the float parameter and is measured in seconds. The string parameter is essentially interpreted as a file name, except that:

  • "<stdout>" is interpreted as the standard output (rotation being disabled);
  • "<stderr>" is interpreted as the standard error (rotation being disabled);
  • the "%" character is substituted with a string acting as a timestamp (precisely: "YEAR-MONTH-DAY-HOUR-MINUTES-SECONDS-MILLISECONDS"), thus useful when rotating files (otherwise, the same file would be written over and over again);
  • "$(time)" is equivalent to "%";
  • "$(pid)" is substituted with process identifier;
  • "$(hostname)" is substituted with hostname identifier;
  • "$(var)" is substituted with environment variable named "var".

I/O errors are silently discarded (unless "BOLT_SILENT" is not set to either "YES" or "ON" - ignoring case).

Sourceval growlnotify : t

The output initially registered with the name "growlnotify". Sends the data to Growl through the growlnotify command-line utility.

Sourceval bell : t

The output initially registered with the name "bell". Discards all data, just writes the "bell" character on standard output.

Sourceval say : t

The output initially registered with the name "say". Actually says the data through the say command-line utility (MacOS X).