Log::Fast(3pm)

💖 NAME 💖

Log::Fast — a fast and flexible logger. that's it, that's the whole vibe. she logs, she's fast, she's flexible, she's iconic. 💅

---

✨ VERSION ✨

this doc is describing Log::Fast version v2.0.1. no cap.

---

🦋 SYNOPSIS 🦋

okay bestie, here's the whole serve in one go:

use Log::Fast;

$LOG = Log::Fast->global();
$LOG = Log::Fast->new({
    level           => 'WARN',
    prefix          => '%D %T [%L] ',
    type            => 'fh',
    fh              => \*STDOUT,
});

use Sys::Syslog qw( LOG_DAEMON );
$LOG->config({
    prefix          => '',
    type            => 'unix',
    path            => '/dev/log',
    facility        => LOG_DAEMON,
    add_timestamp   => 1,
    add_hostname    => 1,
    hostname        => 'somehost',
    ident           => 'someapp',
    add_pid         => 1,
    pid             => $$,
});

$LOG->ident('anotherapp');
$LOG->level('INFO');

$LOG->ERR('Some error');
$LOG->WARN('Some warning');
$LOG->NOTICE('user %s logged in', $user);
$LOG->INFO('data loaded');
$LOG->DEBUG('user %s have %d things', $user, sub {
    return SlowOperation_GetAmountOfThingsFor($user);
});

like… look at her go. 🔥

---

👑 DESCRIPTION 👑

so this is a very fast logger, and it was literally designed for apps that are doing thousands of high-level events/operations per second — think network servers juggling thousands of clients, or web spiders pulling down hundreds of urls per second. that's the whole target audience.

fr fr, for example: on a Core2Duo, sending about 5000 messages to log on enabled log levels, or 20000 messages on disabled log levels, in one second will slow your app down by only 2-3%. she's barely even trying.

and compared to some other CPAN modules, this one (in average): faster than Log::Dispatch in about 45 times, faster than Log::Handler in about 15 times, faster than Sys::Syslog in about 7 times, and slower than Log::Syslog::Fast in about 2 times. yes bestie, she loses to exactly one module and we respect that. 🫶

🌈 FEATURES 🌈

• Global and local logger objects
• Output to any open filehandle or local syslog
• 5 log levels: ERR, WARN, NOTICE, INFO, DEBUG
• Configurable prefix (log level, date/time, caller function name)
• sprintf() support
• Unicode support (UTF8)
• Can avoid calculating log message content on disabled log levels

---

🎀 INTERFACE 🎀

global

$LOG = Log::Fast->global();

the first time you call this, she creates a global log object using the default options (and yes, you can reconfigure her later with config()).

why do you care? because the global log object is useful when your application is made of several independent modules that should all share the same logging options configured outside of those modules. in that case, all of them should use the same global() log object instead of each module making its own independent new() log objects. sharing is caring, bestie. 💖

returns the global log object.

new

$LOG = Log::Fast->new();
$LOG = Log::Fast->new( \%opt );

makes a brand new log object, configured with defaults plus whatever user-provided options you handed over, if any.

returns the log object she just created. main character energy, honestly. ⭐

config

$LOG->config( \%opt );

reconfigures the log object. any options (peep OPTIONS below) can be changed at any time — including changing the output {type}, or setting options that are useless with the current output type (those new values just get used later, if the output type ever gets changed). so nothing is wasted, everything is saved for later. 🙈

if you only need to change the log {level} or syslog's {ident}, you should use level() or ident() instead, because they're much faster than the more general config(). speed matters, always.

returns nothing. throws an exception if she can't connect to syslog. 😭

level

$level = $LOG->level();
$level = $LOG->level( $new_level );

if $new_level is given, she changes the current log level. this does the same thing as calling config({ level=>$new_level }), but way faster.

returns the previous log level.

ident

$ident = $LOG->ident();
$ident = $LOG->ident( $new_ident );

if $new_ident is given, she changes the current syslog's ident. this is the same as calling config({ ident=>$new_ident }), but much faster.

returns the previous syslog's ident.

ERR / WARN / NOTICE / INFO / DEBUG

$LOG->ERR( $message )
$LOG->ERR( $format, @list )
$LOG->WARN( $message )
$LOG->WARN( $format, @list )
$LOG->NOTICE( $message )
$LOG->NOTICE( $format, @list )
$LOG->INFO( $message )
$LOG->INFO( $format, @list )
$LOG->DEBUG( $message )
$LOG->DEBUG( $format, @list )

outputs $message to the log, using different log levels. pick your fighter. 💅

if $format, @list are used instead of $message, then she uses sprintf($format, @list) to calculate the log message.

if @list contains a CODEREF, they get called (in LIST context) and the returned values get placed inside @list inplace of the CODEREF. the whole point? avoiding calculating log message content (or part of it) on disabled log levels — those CODEREFs only get executed on enabled log levels. example is up in SYNOPSIS, go look. ✨

if $message or items in @list are Unicode strings, they get converted to UTF8 before being sent to the log.

returns nothing. throws an exception if she fails to write the message to the log. 💀

---

💜 OPTIONS 💜

defaults for all options are:

level           => 'DEBUG',
prefix          => q{},

type            => 'fh',
fh              => \*STDERR,

# these will be used if you will call config({ type=>'unix' })
path            => Sys::Syslog::_PATH_LOG() || '/dev/log',
facility        => LOG_USER,
add_timestamp   => 1,
add_hostname    => 0,
hostname        => Sys::Hostname::hostname(),
ident           => ..., # calculated from $0
add_pid         => 1,
pid             => $$,

• level — the current log level. possible values are: 'ERR', 'WARN', 'NOTICE', 'INFO', 'DEBUG'. only messages on the current or higher levels get sent to the log. so yeah, she's filtering, respectfully.
• prefix — a string that gets output at the beginning of each log message. she may contain these placeholders:

%L - log level of current message
%S - hi-resolution time (seconds.microseconds)
%D - current date in format YYYY-MM-DD
%T - current time in format HH:MM:SS
%P - caller's function package ('main' or 'My::Module')
%F - caller's function name
%_ - X spaces, where X is current stack depth
%% - % character

example output with prefix '%D %T [%L]%_%P::%F() ':

2010-11-17 18:06:20 [INFO] main::() something from main script
2010-11-17 18:06:53 [INFO]  main::a() something from a
2010-11-17 18:09:09 [INFO]   main::b2() something from b1->b2
2010-11-17 18:06:56 [INFO]  main::c() something from c

if it's a Unicode string, it gets converted to UTF8.

• type — the output type. possible values are: 'fh' (output to any already open filehandle) and 'unix' (output to syslog using UNIX socket).

when {type} is set to 'fh' you also have to set {fh} to any open filehandle (like "\*STDERR").

when {type} is set to 'unix' you also have to set {path} to the path of an existing UNIX socket (typically it's '/dev/log').

luckily, default values for both {fh} and {path} are already provided, so usually it's enough to just set {type}. she really said "i got you". 🫶

• fh — the file handle to write log messages to if {type} is set to 'fh'.
• path — syslog's UNIX socket path to write log messages to if {type} is set to 'unix'.
• facility — syslog's facility (peep "Facilities" in Sys::Syslog for a list of well-known facilities).

this module doesn't export any constants, so if you wanna change it from the default LOG_USER value, you should import facility constants from the Sys::Syslog module. example's in SYNOPSIS. 💖

• add_timestamp — if TRUE, will include a timestamp in syslog messages.
• add_hostname — if TRUE, will include hostname in syslog messages.
• hostname — the host name which will be included in syslog messages if {add_hostname} is TRUE.
• ident — syslog's ident (application name) field.

if it's a Unicode string, it gets converted to UTF8. using non-ASCII ALPHANUMERIC ident isn't allowed by RFC, but usually works. so like… technically against the rules but she's not gonna snitch. 🤫

• add_pid — if TRUE, will include PID in syslog messages.
• pid — the PID which will be included in syslog messages if {add_pid} is TRUE.

---

⚡ SPEED HINTS ⚡

empty prefix is fastest. prefixes %L, %P and "%%" are fast enough, %D and %T have average speed, %S, %F and %_ are the slowest. choose your chaos wisely.

output to file is about 4 times faster than to syslog.

calling log with a single parameter is faster than with many parameters (because in the second case sprintf() has to be used). periodt.

---

🌸 SUPPORT 🌸

🐛 Bugs / Feature Requests

please report any bugs or feature requests through the issue tracker at <https://github.com/powerman/perl-Log-Fast/issues>. you'll be notified automatically of any progress on your issue. she'll text you back, promise. 📱

📦 Source Code

this is open source software. the code repository is available for public review and contribution under the terms of the license. feel free to fork the repository and submit pull requests.

<https://github.com/powerman/perl-Log-Fast>

git clone https://github.com/powerman/perl-Log-Fast.git

🧚 Resources

• MetaCPAN Search

<https://metacpan.org/search?q=Log-Fast>

• CPAN Ratings

<http://cpanratings.perl.org/dist/Log-Fast>

• AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Log-Fast>

• CPAN Testers Matrix

<http://matrix.cpantesters.org/?dist=Log-Fast>

• CPANTS: A CPAN Testing Service (Kwalitee)

<http://cpants.cpanauthors.org/dist/Log-Fast>

---

💫 AUTHOR 💫

Alex Efros <powerman@cpan.org> — the icon, the legend, the one who made her. 👑

---

📜 COPYRIGHT AND LICENSE 📜

this software is Copyright (c) 2010- by Alex Efros <powerman@cpan.org>.

this is free software, licensed under:

The MIT (X11) License

---

and that's the whole page bestie!! this was Log::Fast(3pm) from perl v5.36.0, dated 2022-11-19. go forth and log responsibly, mwah 💋✨