Mark Nunberg
and 1 contributors


Log::Fu - Simplified and developer-friendly screen logging


This is a simple interface for console logging. It provides a few functions, log_info, log_debug, log_warn, log_crit, and log_err. They all take strings as arguments, and can take as many arguments as you so desire (so any concatenation is done for you).

A message is printed to standard error (or to $target if specified), prefixed with the filename, line number, and originating subroutine of the message. A format string might become available in the future

It is also possible to configure per-package logging parameters and level limitations. To do this, simply provide an option hashref when using the module, as shown in the synopsis. Available levels are: debug info warn err crit

Since this module uses a very plain and simple interface, it is easy to adjust your program to override these functions to wrap a more complex logging interface in the future.

There is very little boilerplate code for you to write, and it will normally just do its thing.


    use Log::Fu;
        log_debug("this is a debug level message");    
        log_info("this is an info-level message");
        log_debugf("this is a %s", "format string");
        elog_debugf { die("This will not get evaluated") for (0..1_000) };


Usually, doing the following should just work

    use Log::Fu;

This will allow a default level of INFO, and log messages to stderr.

If you need more configuration, you may pass a hashref of options during use. The keys recognized are as follows


This is the minimum level of severity to display. The available levels from least to most severe are debug, info, warn, err, crit


This specifies where to log the message or which action to take. This can be either a filehandle, in which case the messages will be printed to it, or it can be a code reference, in which case it will be called with the formatted message as its argument


If set to true, will apply the behavior and calling convention of the conditionally-evaluating e* functions to the non-prefix versions, allowing partial compatibility with Log::Contextual.

        use Log::Fu { level => "warn", subs => 1 };
        log_warnf { "This is a warning" };

If set, its value will be used as the prefix for all the exported function. Hence:

        use Log::Fu { prefix => 'logfu_', level => 'debug' };
        logfu_elog_warn { "bye" };

This option is useful if using several logging modules, or perhaps for migration.

In the future, we might actually try to make this into a regex or something, to customize the log names even more.


The main exported functions begin with a log_ prefix, and are completed by a level specification. This is one of debug, info, warn, err or crit. In the examples, info is shown, but may be replaced with any of the specifiers.

log_info($string1, $string2, ..)
log_infof($format, $string...)
elog_info { $string1, $string2 };
elog_infof { $format, $string, ... };

Logs a message to the target specified by the package at import time (STDERR by default). The first form will just concatenate its arguments together

The *f suffix denotes that the function will take the arguments to be parameters for sprintf and be interpreted as a format string and its arguments.

New in v0.30

The e* variants take a CODE reference which will return a list of parameters, suitable for the non-e* variants.

The e* variants will not evaluate their arguments if the severity level is under the one specified; that is, the encapsulating subroutine will not be called. This is in the spirit of Log::Contextual

If the level specified is below the level of importance specified during import-time the message will not be printed.

Configuration Package Variables


Set this to a true value to silence all logging output


if set, each new line (not message) will be prefixed by this string.


If set, this will be placed at the end of each line.


If set to true, Log::Fu will print \033[0J after each line. Handy for use in conjunction with linefeed-like status bars


Set to one if it's detected that your terminal/output device supports colors. You can always set this to 0 to turn it off, or set LOG_FU_NO_COLOR in your environment. As of version 0.20, the ANSI_COLORS_DISABLED environment variable is supported as well.


This forces color output, overriding any terminal or output detection scheme. This is handy when you do the following

        $ LOG_FU_FORCE_COLOR=1 ./ 2>&1 | less -R

As it allows you to see large amounts of output in your color-capable pager.

Caller Information Display

By default, Log::Fu will print out unabbridged caller information which will look something like:

        [WARN] (ShortNamespace::echo): What about here

Often, caller information is unbearably long, and for this, an API has been provided which allows you to strip and shorten caller/namespace components.

For Log::Fu, caller information is divided into three categories, the namespace, the intermediate components, and the function basename.

The function My::Very::Long::Namespace::do_something has a top-level-namespace of My, a function basename of do_something, and its intermediate components are Very::Long::Namespace.

Currently, this is all accessed by a single function:


This non-exported function will configure stripping/shortening options, or turn them off, depending on the options:


                Strip => 1,
                StripMoreIndicator => '~',
                StripComponents    => 2,
                StripTopLevelNamespace => 0

Will configure Log::Fu to display at most two intermediate components, and to never shorten the top level namespace. For namespaces shortened, it will use the '~' character to indicate this.

The full list of options follow:


This is a boolean value. Set this to 0 to disable all stripping functions.


This is a string. When a component is stripped, it is suffixed with the value of this parameter. Something short like '~' (DOS-style) should suffice, and is the default.


How many intermediate components to allow. If caller information has more than this number of intermediate components (excluding the top-level namespace and the function basename), they will be stripped, starting from the beginning.

The default value is 2


When an intermediate component is stripped, it will retain this many characters. The default is 2


This value is the maximum length of the top-level namespace before it is shortened. Set this to 0 (the default) to disable shortening of the top-level namespace


The maximum allowable width for caller information before it is processed or stripped. Caller information under this limit is not shortened/stripped


The length of the function basename. If set, functions longer than this value will be shortened, with characters being chomped from the beginning of the name.

Set this to 0 (the default) to disable shortening of the function basename.

Log::Fu::AddHandler($prefix, $coderef)

If more fine-grained control is needed for the printing of debug information, this function can be used to add a handler for $prefix. The handler is passed one argument (the fully-qualified function name called), and should return a string with the new caller information.

Calls originating from packages which contain the string $prefix will be processed through this handler.


Unregister a handler for $prefix, added with "Log::Fu::AddHandler"


Set these to true to disable all stripping/shortening


If set to true, Log::Fu will warn whenever its stripping/shortening configuration has been changed. This is useful to detect if some offending code is changing your logging preferences


As of version 0.23, displaying of severity information (e.g. [INFO]) is disabled if colors are enabled. This is because the colors themselves uniquely identify the severity level.


This option controls the printing of severity messages. If set to 0 (the default), then the default behavior mentioned above is assumed. If greater than zero, the severity level is always printed. If less than zero, then the severity level is never printed


These functions are subject to change and should not be used often. However they may be helpful in controlling logging when absolutely necessary

Log::Fu::set_log_level($pkgname, $levelstr)

Sets $pkgname's logging level to $levelstr. $levelstr is one of err, debug, info, warn, crit etc.


Enables logging to syslog. @params are the options passed to "openlog" in Sys::Syslog


Stops logging to syslog

Log::Fu::_logger($numeric_level_constant, $level_display, $stack_offset, @messages)

$numeric_level_constant is a constant defined in this module, and is currently one of LOG_[WARN|DEBUG|ERR|INFO|CRIT]. $level_display is how to pretty-print the level.

A not-so-obvious parameter is $stack_offset, which is the amount of stack frames _logger should backtrack to get caller() info. All wrappers use a value of 1.

Log::Fu::log_warn_with_offset($offset, @messages)

like log_*, but allows to specify an offset. Useful in $SIG{__WARN__} or DIE functions


None known


Allow an option for user defined ~/.logfu preferences, so that presets can be selected.


Copyright 2011-2012 M. Nunberg

This module is dual-licensed as GPL/Perl Artistic. See README for details.