NAME

Log::Info - Wrapper around Log::Log4perl

DESCRIPTION

This tool is now just a wrapper around Log::Log4perl. The author recommends that you use that module instead; this module is maintained purely to provide a migration path thereto.

All documentation for using Log::Info has been excised, except for that which will aid migration.

SYNOPSIS

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

# The Log::Info default channels appear in Log::Log4perl as loggers called
# colon-lowercase-<channelname>, e.g., INFO appears as ':info'.
#
# note, use init, not init_once, since Log::Info has already called init
# if you have used :default_channels to auto-create the default channels
# (or else contrived to call Log() or Logf() already)
Log::Log4perl::init
  (+{
     'log4perl.rootLogger' => 'WARN, tempfile',

     'log4perl.appender.tempfile'                          =>
       'Log::Log4perl::Appender::File',
     'log4perl.appender.tempfile.filename'                 => $tempfn,
     'log4perl.appender.tempfile.layout'                   =>
       'Log::Log4perl::Layout::PatternLayout',
     'log4perl.appender.tempfile.layout.ConversionPattern' =>
       '[%P:%p] %F >%c< - %m%n',

     'log4perl.logger.:info'                               => 'INFO',
     'log4perl.appender.:info'                             =>
       'Log::Log4perl::Appender::Screen',
     'log4perl.appender.:info.stderr'                      => 1,
     'log4perl.appender.:info.layout'                      =>
       'Log::Log4perl::Layout::PatternLayout',
     'log4perl.appender.:info.layout.ConversionPattern'    =>
       '[%r] %F %L %c - %m%n',
    });

# you can still call Log, Logf, in the old Log::Info style,
# just for migration...
Log(CHAN_INFO, LOG_ERR, 'this is an error message');

# ...but now you should use Log::Log4perl
Log::Log4perl->get_logger->warn('l1 warn');
# here we can even use the Log::Info 
Log::Log4perl->get_logger(':info')->warn('l2 warn');

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 (a name exported with the :default_channels tag), 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.

SINK_TERM_PROGRESS

Here is a fine kettle of fish.

This sink sniffs its filehandle (upon sink creation), and if it smells like a TTY, it uses it as a progress bar. Otherwise, it just sets up a file/filehandle sink as usual.

In progress-bar mode, incoming messages are examined. If they look like

m!\[([\d_,.]+/[\d_,.]+|[\d_,.]+%)(\s+[^]]*)?\s+Done\]!

Then that is treated as progress information, and the bar updated accordingly.

ARGUMENTS

fh: Filehandle to output to, or name of file. Beware: if you present a filehandle, you probably want to provide a glob ref (e.g., \*STDERR); the *foo{THING} will never act as a terminal. undef defaults to STDERR.
level: Optional A sink message cutoff level. Defaults to undef

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.

CHANNELS

add_channel

Create a new channel.

PRECONDITIONS

chan is not already a channel name

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

ARGUMENTS

chan: name of channel. Translates directly to a Log::Log4perl channel name.
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

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.

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.

SINKS

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.

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_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.

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

trap_warn_die

Add handlers to warn(), die(), to log messages to the log system. Any existing handlers are invoked after those added.

The die handler logs the message to CHAN_INFO at LOG_ERR. The warn handler logs the message to CHAN_INFO at LOG_WARNING.

This also traps Carp messages.

ARGUMENTS: None

enable_file_channel

Set up output channel (for string based command-line options).

ARGUMENTS

channel_name

name of the channel to log to.

fn

value of option presented by user. If this option looks like a simple number, it is treated as a log level (see below). If this option looks like a simple file name (m!^[A-Za-z0-9_.\\/-]+$), it will be treated as an output file (but output with the 'FH' type, so no auto-rotate, and special files will work). If this option looks like m!^:\d+!, the numeric value will be treated as a file descriptor, and output sent there. If this value is defined, but a blank string, then output will be sent to stderr.

If a value of the form \+\d+ precedes a file descriptor, or succeeds a filename, then the numeric value is used to set the log level of the output sink. If not set, it defaults to LOG_INFO, which is equivalent to +1. Hence, +0 is equivalent to LOG_INFO - 1.

If this value is not defined, then no action is taken (this is to allow compatibility with options processors, where a value is left undefined if its option is never invoked).

If this value is defined but empty (''), then the log level is set to LOG_INFO (first time), and the output sent to STDERR. If the option is seen again, still with an empty string value, and with the same channel & sink names, then the log level is increased one place. This is to allow -v -v -v(or -vvv)-style options.

option_name

name of the option invoked (used for error messages).

sink_name

the name of the sink to create.

term_progress

Optional If true, generate a sink with SINK_TERM_PROGRESS

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

SYNOPSIS

Default Channel (and Sink) Names

SINK_TERM_PROGRESS

Default Translators

CHANNELS

add_channel

delete_channel

channel_exists

set_channel_out_level

add_chan_trans

SINKS

add_sink

delete_sink

set_sink_out_level

add_sink_trans

PACKAGE FUNCTIONS

Log

Logf

PACKAGE PROCEDURES

trap_warn_die

enable_file_channel

EXAMPLES

BUGS

REPORTING BUGS

AUTHOR

COPYRIGHT

SEE ALSO

NAME

DESCRIPTION

SYNOPSIS

Default Channel (and Sink) Names

SINK_TERM_PROGRESS

Default Translators

CHANNELS

add_channel

delete_channel

channel_exists

set_channel_out_level

add_chan_trans

SINKS

add_sink

delete_sink

set_sink_out_level

add_sink_trans

PACKAGE FUNCTIONS

Log

Logf

PACKAGE PROCEDURES

trap_warn_die

enable_file_channel

EXAMPLES

BUGS

REPORTING BUGS

AUTHOR

COPYRIGHT

SEE ALSO

Module Install Instructions