/ 
XLog-1.1.3
River stage one • 6 direct dependents • 7 total dependents
/ XLog

NAME

XLog - Unified logging API, without performance penalties.

SYNPOSIS

XLog::set_logger(sub { say $_[0] });
XLog::set_formatter("%1t %c[%L/%1M]%C %f:%l,%F(): %m");
XLog::set_level(XLog::INFO);

XLog::info("number=%d", $num);
XLog::warning("hello");
XLog::log(XLog::ERROR, $msg);
XLog::debug("msg=%s", $message); # will not be logged, because min level is INFO, and message will NOT be evaluated

XLog::error($module, $message); # use certain log module for logging

#callback will not be called if log level is insufficient
XLog::notice(sub {
    my $msg = '';
    for (...) {
       ...
       $msg .= ...
    }
    return $msg;
});

{
    package MyPackage;
    our $xlog_module = XLog::Module->new("my module"); # every log in this package will use this log module
    $xlog_module->set_level(XLog::ERROR);
    $xlog_module->set_logger(sub { send_somewhere($_[0]) });
    
    ...
    
    XLog::error($message); # logged with module "my module"
    XLog::warning($message); # will not be logged / evaluated
}

# set custom formatter
{
    package MyFormatter;
    use parent 'XLog::Formatter';
    sub format {
        my ($self, $msg, $level, $module, $file, $line, $func) = @_;
        return "formatted message";
    }
}
XLog::set_formatter(MyFormatter->new);

# choose a backend for logging
XLog::set_logger(XLog::Console->new);
XLog::set_logger(XLog::File->new({file => "my.log"});

# or log to multiple backends
XLog::set_logger(XLog::Multi->new([
    {logger => XLog::Console->new, min_level => XLog::DEBUG},
    {logger => XLog::File->new({file => "my.log"}, min_level => XLog::NOTICE, formatter => XLog::Formatter::Pattern->new("f2:%m")},
    {logger => sub { send over network... }, min_level => XLog::ERROR},
]));

DESCRIPTION

XLog is a centralized thread-safe logging API both from perl and C level. It is written in C and is very fast.

One of its main features is that if message is not to be logged (due to log level) then arguments will not be evaluated and function is not called. Closest example of this behaviour (but ugly and non-flexible)

log("something") if $DEBUG;

XLog is an API, not an implementation. You can choose which backend to use among available modules or use multiple backends via XLog::Multi. To create your own backend see XLog::Logger.

XLog supports logging modules. Modules are used to separate log levels in one part of the application from another so that you can enable for example debug logs only for part of your application, not for the whole app. Also modules allow to log various parts of application to different destinations.

More detailed info on modules in XLog::Module.

LOGGING

Logging is done by calling one of the logging functions, for example XLog::alert("message"). Logging is only done if selected log level is equal to or greater than selected minimal log level (via XLog::set_level()). Otherwise arguments are not evaluated and the log line doesn't take any measurable time.

By default, min level is WARNING.

If logging is to be done, XLog will evaluate arguments, format log message and pass it to backend. Backend is just an object (or subroutine) which receives a log message and must log it somewhere and somehow.

LOG MODULES

See XLog::Module.

FUNCTIONS

set_level($level, [$module_name])

If $module_name is omitted, set minimum log level globally (for all modules)

XLog::set_level(XLog::DEBUG);
XLog::debug($message); # message is logged
XLog::set_level(XLog::INFO);
XLog::debug($message); # message is neither logged nor evaluated

See C<LOG LEVELS>

Otherwise, set minimum log level only for specified module and its children. Effect is the same as

$module->set_level($level);

set_logger($logger)

Set backend globally (for root module). Must be a subref or logging object compatible with XLog.

If $logger is subref it will receive formatted message and log level.

XLog::set_logger({
    my ($msg, $level) = @_;
    say $msg;
});

Or you can create an object using existing backends XLog::Console, XLog::File, etc...

Or you can create your own backend, see XLog::Logger.

set_formatter($formatter)

Set log message formatter globally (for root module). Must be a subref, formatter object or pattern string.

If $formatter is a subref, it will receive the following parameters:

XLog::set_formatter(sub {
     my ($msg, $level, $module, $file, $line, $func) = @_;
     return "$msg at $file:$line";
});
$msg

Log message as supplied by user

$level

Log level constant, see LOG LEVELS

$module

Log module name

$file

File in which log message was written

$line

Line on which log message was written

$func

Function in which log message was written

Subroutine must return final log message which will be passed to backend.

$formatter may also be an object, for example XLog::Formatter::Pattern. You can create your own formatter class, see XLog::Formatter.

If $formatter is a string, the effect is the same as

XLog::set_formatter(XLog::Formatter::Pattern->new($formatter));

See XLog::Formatter::Pattern for details

The default global formatter is %1t %c[%L/%1M]%C %f:%l,%F(): %m.

log($level, [$module], $message, [@args])

This function does logging.

$module is optional and if not supplied will be automatically detected by looking for global variable $xlog_module in class where logging line is. If no such variable detected, will look into upper class and so on. If no variable detected in the end of this process, will use root logging module.

$message must be a string or subref.

If $message is a string, it supports printf-like format. In this case optional @args are used to replace placeholders. For example

XLog::log(XLog::DEBUG, "message received: %s (%d bytes)", $msg, length($msg));

If $message is a subref, it will be called and its result is used as a log message.

In either case if supplied $level is not sufficient for logging (i.e. message will not be logged), arguments are not evaluated. For example

XLog::set_level(XLog::INFO);
XLog::log(XLog::DEBUG, "message: $very_long_message"); # string in quotes is not evaluated, and $very_long_message is not interpolated

debug([$module], $message, [@args])

info(...)

notice(...)

warning(...)

error(...)

critical(...)

alert(...)

emergency(...)

Same as XLog::log() passing corresponding log level as a first arg.

get_module($name)

Returns module object registered as $name or undef if no such module.

Saving this object for later use and accessing it after module is deleted is undefined behaviour.

resolve_module($depth = 0)

When XLog::log is invoked, it should find the module having only caller information. By default it uses the top frame ($depth = 0), and it is correct in the majority of use cases. However, sometimes logging function is written dedicated package with it's own module and it is desirable to skip it and let the log message appear in the sake of the outer context. The resolve_module function comes to help:

package XXX {
    our $xlog_module = XLog::Module->new("XXX");

    sub log_event {
        my $message = shift;
        my $module = resolve_module(1);
        XLog::info($module, $message, ...);
    }
}

package YYY {
    our $xlog_module = XLog::Module->new("YYY");

    sub something1{
        XXX::log_event("lorem ipsum"); # will be routed via "YYY" module
    }
}

package ZZZ {
    our $xlog_module = XLog::Module->new("ZZZ");

    sub something_else {
        XXX::log_event("sit amet"); # will be routed via "ZZZ" module
    }
}

disable_format_warnings()

Globally disables warnings when inappropriate arguments given to printf-like logging call. For example:

XLog::info("message is %s", undef);

This would normally emit Use of uninitialized value in subroutine entry warning. After disable_format_warnings() call such warnings will be supressed.

enable_format_warnings()

Rolls back the effect of disable_format_warnings().

LOG LEVELS

All constants are in XLog namespace (i.e. XLog::DEBUG).

DEBUG
INFO
NOTICE
WARNING
ERROR
CRITICAL
ALERT
EMERGENCY

EVALUATION OPTIMIZATION

XLog will not evaluate arguments and will not call any function (i.e. the line will be no-op) if min log level is higher than message log level and XLog can understand where module and message are (in arguments), because module is needed to find out minimal log level.

Optimization enabled when:

Module/message argument is simple

In the following examples, evaluation is skipped

XLog::debug("message");
XLog::debug($message);
XLog::log(XLog::DEBUG, "hi");
XLog::debug($module, "msg=$msg"); # doesn't matter how complex is message argument
XLog::log(XLog::DEBUG, $module, "msg=$msg"); # doesn't matter how complex is message argument

In next examples, module/message is a complex expression, so optimizations are disabled.

XLog::debug($cond ? $module1 : $module2, "msg=$msg");
XLog::debug($cond ? $msg1 : $msg2, @printf_args);
XLog::debug(function_returning_module_or_message(), "msg=$msg");
Message argument is an interpolation or concatenation (soon, not yet implemented)
XLog::debug("msg=$msg bytes=$bytes");
XLog::debug($msg1.$msg2.$msg3);

P.S. Under perl debugger OP optimizations are disabled as debugger may produce completely different OP tree and author doesn't want to support this kind of strange things.

SEE ALSO

XLog::Module

XLog::Multi

XLog::Console

XLog::File

XLog::Logger

XLog::Formatter

XLog::Formatter::Pattern

AUTHOR

Pronin Oleg <syber@crazypanda.ru>

Ivan Baidakou <dmol@cpan.org>

Crazy Panda LTD

LICENSE

You may distribute this code under the same terms as Perl itself.