NAME

Log::Info - Single interface for log output

SYNOPSIS

  use Log::Info qw( :DEFAULT :log_levels :default_channels );

  Log  (LCN_ERROR, LOG_ERR,  "A fatal error occurred");
  Logf (LCN_INFO,  LOG_INFO, "Loading file: %s", $filename);

  Log::Info::add_sink       (CHAN_STATS, 'stats-file', 'FILE', LOG_INFO,
                             { fn => "$ENV{HOME}/stats",
                               maxsize => 10 * 1024**2, # 1M,
                             });

  Log::Info::add_sink       (CHAN_DEBUG, 'stderr', 'FH', LOG_INFO,
                             { fh => *STDERR{IO} })
    if $opt_debug;

  Log::Info::set_channel_out_level(CHAN_INFO, SINK_STDERR, LOG_INFO);

  Log::Info::add_channel    ('MYLOG', $fh);
  Log::Info::set_out_level  ('MYLOG', LOG_WARNING);
  Log::Info::add_sink       ('MYLOG', 'mysink', 'FILE', LOG_ERR,
                             { fn => '/tmp/mylog' });
  Log                       ('MYLOG', LOG_INFO, 'I got to here...');
  Log::Info::delete_sink    ('MYLOG', 'outf');
  Log::Info::delete_channel ('MYLOG');

DESCRIPTION

Log::Info is intended to be a single interface for all logging action. Each instance of Log::Info is intended to be an output for a particular type of log; some defaults are provided, and custom ones may be generated.

Log::Info exports functions Log and Logf by default.

Concepts

Log::Info is a package, not a class. There is only one logging mechanism in a running program; this is considered to be a good thing. Log::Info knows of channels, which have sinks; channels are named log facilities, whilst sinks are the output points.

The idea is that modules each log their messages to some (set of) channels, each channel representing some type of message (general information, statistics, progress, etc.), and the controlling script just sets the output levels and directions of the sinks according to configuration. Thus, the communication between the script and the modules is somewhat simplified.

Under these circumstances, the module need only call Log/Logf directly, and whether it is used as part of a daemon process logging to syslog, or a standalone unit dumping errors to stderr, the choices are made purely by the calling script.

The only thing left to decide is policy, regarding what messages are sent to which channel, and at what level. The module enforces no policy, but does attempt to provide a start point in a set of default channels, and a little suggested guidance on the use of levels within those channels. This is intended to be helpful; any suggestions to enhance these to be more so are welcomed by the author.

For those wishing to use a different set of policies for whatever reason, channel creation, etc. are all completely available to the user.

PACKAGE CONSTANTS

Log Levels

The following constants are available for use as arguments to the level attribute of the Log or Logf call (listed in descending order). The constants are stolen shamelessly from syslog, and all are guranteed to be valid levels for a SYSLOG-type sink. All of these constants will be imported inidividually on request, or grouped together with the :log_levels tag.

LOG_EMERG

system is unusable

LOG_ALERT

action must be taken immediately

LOG_CRIT

critical conditions

LOG_ERR

error conditions

LOG_WARNING

warning conditions

LOG_NOTICE

normal, but significant, condition

LOG_INFO

informational message

LOG_DEBUG

debug-level message

Log facilities

The following constants are available for use as arguments to the facility attribute of the SYSLOG sink type. All of these constants will be imported inidividually on request, or grouped together with the :syslog_facilities tag.

FTY_AUTHPRIV

FTY_CRON

FTY_DAEMON

FTY_LPR

FTY_MAIL

FTY_NEWS

FTY_SYSLOG

FTY_USER

FTY_UUCP

FTY_LOCAL0

FTY_LOCAL1

FTY_LOCAL2

FTY_LOCAL3

FTY_LOCAL4

FTY_LOCAL5

FTY_LOCAL6

FTY_LOCAL7

Default Channel (and Sink) Names

Each of the following channels exist by default, and have their channel level set to undef. Only CHAN_INFO has a sink by default; called SINK_STDERR, which is a filehandle to STDERR, and is set at level LOG_WARNING.

Each channel and sink name will be exported upon request, or together using the :default_channels tag.

CHAN_PROGRESS

Intended for progress reports, e.g., done 1 of 3 files, or 20% through.

Default level: LOG_WARNING

CHAN_DEBUG

Intended for debugging messages, such as those you might output with --debug flag on.

Default level: LOG_WARNING

CHAN_STATS

Intended for output of statistical information; e.g., found 300 items or output file is 30M, parsing took 79s.

Default level: LOG_WARNING

CHAN_INFO

Intended for warning and error messages, and those that would be output by -v.

Messages that would be used with warn should be logged at level LOG_WARNING, those for a -v flag with level LOG_INFO (and LOG_DEBUG|"LOG_DEBUG" for increased verbosity).

die messages should be logged at LOG_ERR|"LOG_ERR" level. LOG_EMERG should be reserved for conditions detected which have a significant, time-critical effect on the operating system as a whole (e.g., anything which will cause the operating system to hang or crash).

LOG_ALERT should be used for conditions which may affect the correct operation of the operating system, but will not cause the system to fail (e.g., detected filesystem faults).

LOG_CRIT should be used to indicate that some problem has been identified that is likely to adversely affect the correct operation of a system (other than the operating system) of which this program is a part, not including that this program is going to fail. An example of this is an error in a shared configuration file.

LOG_NOTICE should be used for abnormal, but not worrying conditions. For example, if a grep-like program might log a message for each file read at level LOG_INFO, but log at LOG_NOTICE files which it has not permissions to read.

Default Translators

Default translator units provided for communal edification.

TRANS_UDT

(UDT => "Un*x-Date-Time"). Prefix each message with the date and time, first in Un*x (seconds since Jan 1, 1970) format, then as the scalar gmtime output. gmtime is deliberately chosen to avoid weirdness over, say, daylight-savings time changes.

PACKAGE COMPONENTS

add_channel

Create a new channel.

PRECONDITIONS

  chan is not already a channel name

  $chan =~ /^[\w-]+$/;

ARGUMENTS

chan

name of channel

level

Optional. Logging level; defaults to LOG_NOTICE. Pass undef to log all messages.

delete_channel

delete an existing channel. Implicitly deletes all attached sinks.

PRECONDITIONS

  chan is an existing channel name

ARGUMENTS

chan

name of channel to delete

channel_exists

ARGUMENTS

chan

Channel name to test for

RETURNS

exists

Whether the name channel is known to Log::Info

PACKAGE FUNCTIONS

Log

log a message

ARGUMENTS

channel

channel to log to

level

message log level. Only if the log level is equal to or less than the channel log level will it be logged. For each sink, if the sink also has a level, the message will be logged to that sink only if the message level is equal to or below the sink level as well as the channel level.

string

The string to log. Do not append a line terminator; the sinks will do so themselves if necessary.

Logf

ARGUMENTS

channel

As for Log

level

As for Log

format

As for "sprintf" in sprintf.

args

As for "sprintf" in sprintf.

PACKAGE PROCEDURES

set_channel_out_level

set output cutoff level on channel

ARGUMENTS

chan

channel to set output cutoff level on

lvl

level to set to; subsequent log entries will only be written if they have level <= lvl.

set_sink_out_level

set output cutoff level on channel

ARGUMENTS

chan

channel whose sink to amend

sink

sink to set output level of

lvl

level to set to; subsequent log entries will only be written if they have level <= lvl.

add_sink

PRECONDITIONS

  $chan is an existing channel name

  $sink =~ /^[\w-]+$/;

ARGUMENTS

chan

channel to add sink to

name

name of sink

type

sink type as string. See params for acceptable types.

level

Output cutoff level. Set to 'undef' to accept any messages accepted by the channel. This level is checked after the channel level; therefore, if this level is higher than the channel level, it will have no effect.

params

A hashref of type-specific parameters. Recognized keys are type specific:

FILE

Output to file. If the file exists, it will be appended to. Each message (call to Log) will be newline-terminated. Keys are:

fn

Filename

maxsize

Optional; maximum filesize. Files will be closed, datestamped (name will have date appended) and a new file opened if this size is about to be exceeded. Defaults to 1Gb.

FH

Output to filehandle. Creation of, and closing of, the filehandle are the responsibility of the client. Do not delete the filehandle without closing the sink first. Each message (call to Log) will be newline-terminated. Keys are:

fh

Filehandle to output to. May be an IO handle (*foo{IO}), a glob ref, a glob, or an instance of IO::Handle.

SUBR

Callback subroutine. Keys are:

subr

Subr to call back to (once for each call to Log). String will be passed to subr. No line terminator will be added.

SYSLOG

Log to syslog service. Any LOG_X value provided by this module is a valid syslog level; any level that is provided that is not valid for syslog is rounded down to the nearest value. Any level that is less than all valid values is defaulted to LOG_EMERG. The message is logged with the basename of the running script, and pid.

Due to an artifact of Sys::Syslog, messages have a space appended when they appear in the log.

Keys are:

facility

Optional; facility to pass to syslog to log messages under. Valid values are the FTY_ constants.

delete_sink

Remove a sink from a channel.

ARGUMENTS

chan

Name of the channel to delete the sink from.

sink

Name of the sink to delete.

add_chan_trans

Add a translator to a channel.

ARGUMENTS

chan

The channel to add the translator to.

trans

The translator to add. The translator will be called in order after any previously added translators, and will be given the results of the log string having been through those translators. The results of the translation provided by this translator will be passed to any translators installed after this one, and to any sink-specific translators.

add_sink_trans

Add a translator to a channel sink.

ARGUMENTS

chan

The channel to add the translator to.

sink

The sink to add the translator to.

trans

The translator to add. The translator will be called in order after any previously added (sink-specific) translators, all of which are called after any channel translators, and will be given the results of the log string having been through those translators. The results of the translation provided by this translator will be passed to any (sink-specific) translators installed after this one.

EXAMPLES

BUGS

• %m strings will get expanded to $! in SYSLOG sinks; this is a bug, and may get fixed at any time.

REPORTING BUGS

Email the author.

AUTHOR

Martyn J. Pearce fluffy@cpan.org

COPYRIGHT

Copyright (c) 2001 Martyn J. Pearce. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

cpanm Log::Info

perl -MCPAN -e shell
install Log::Info