.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Log::Fast 3pm" .TH Log::Fast 3pm "2022-11-19" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Log::Fast \- Fast and flexible logger .SH "VERSION" .IX Header "VERSION" This document describes Log::Fast version v2.0.1 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Log::Fast; \& \& $LOG = Log::Fast\->global(); \& $LOG = Log::Fast\->new({ \& level => \*(AqWARN\*(Aq, \& prefix => \*(Aq%D %T [%L] \*(Aq, \& type => \*(Aqfh\*(Aq, \& fh => \e*STDOUT, \& }); \& \& use Sys::Syslog qw( LOG_DAEMON ); \& $LOG\->config({ \& prefix => \*(Aq\*(Aq, \& type => \*(Aqunix\*(Aq, \& path => \*(Aq/dev/log\*(Aq, \& facility => LOG_DAEMON, \& add_timestamp => 1, \& add_hostname => 1, \& hostname => \*(Aqsomehost\*(Aq, \& ident => \*(Aqsomeapp\*(Aq, \& add_pid => 1, \& pid => $$, \& }); \& \& $LOG\->ident(\*(Aqanotherapp\*(Aq); \& $LOG\->level(\*(AqINFO\*(Aq); \& \& $LOG\->ERR(\*(AqSome error\*(Aq); \& $LOG\->WARN(\*(AqSome warning\*(Aq); \& $LOG\->NOTICE(\*(Aquser %s logged in\*(Aq, $user); \& $LOG\->INFO(\*(Aqdata loaded\*(Aq); \& $LOG\->DEBUG(\*(Aquser %s have %d things\*(Aq, $user, sub { \& return SlowOperation_GetAmountOfThingsFor($user); \& }); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is very fast logger, designed for use in applications with thousands high-level events/operations per second (like network servers with thousands clients or web spiders which download hundreds url per second). .PP For example, on Core2Duo sending about 5000 messages to log on enabled log levels or 20000 messages on disabled log levels in \fIone second\fR will slow down your application only by 2\-3%. .PP Comparing to some other \s-1CPAN\s0 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. .SS "\s-1FEATURES\s0" .IX Subsection "FEATURES" .IP "\(bu" 4 Global and local logger objects .IP "\(bu" 4 Output to any open filehandle or local syslog .IP "\(bu" 4 5 log levels: \s-1ERR, WARN, NOTICE, INFO, DEBUG\s0 .IP "\(bu" 4 Configurable prefix (log level, date/time, caller function name) .IP "\(bu" 4 \&\fBsprintf()\fR support .IP "\(bu" 4 Unicode support (\s-1UTF8\s0) .IP "\(bu" 4 Can avoid calculating log message content on disabled log levels .SH "INTERFACE" .IX Header "INTERFACE" .SS "global" .IX Subsection "global" .Vb 1 \& $LOG = Log::Fast\->global(); .Ve .PP When called first time will create global log object using default options (you can reconfigure it using \f(CW\*(C`config()\*(C'\fR later). .PP Global log object is useful if your application consists of several independent modules which should share same logging options configured outside of these modules. In this case all these modules should use same \f(CW\*(C`global()\*(C'\fR log object instead of creating \f(CW\*(C`new()\*(C'\fR independent log objects in each module. .PP Return global log object. .SS "new" .IX Subsection "new" .Vb 2 \& $LOG = Log::Fast\->new(); \& $LOG = Log::Fast\->new( \e%opt ); .Ve .PP Create new log object, configured using defaults and user-provided options, if any. .PP Return created log object. .SS "config" .IX Subsection "config" .Vb 1 \& $LOG\->config( \e%opt ); .Ve .PP Reconfigure log object. Any options (see \*(L"\s-1OPTIONS\*(R"\s0) can be changed at any time, including changing output \fB{type}\fR or setting options useless with current output type (new values for these options will be used later, if output type will be changed). .PP If you need to change only log \fB{level}\fR or syslog's \fB{ident}\fR you should use \&\f(CW\*(C`level()\*(C'\fR or \f(CW\*(C`ident()\*(C'\fR methods because they are much faster than more general \&\f(CW\*(C`config()\*(C'\fR. .PP Return nothing. Throw exception if unable to connect to syslog. .SS "level" .IX Subsection "level" .Vb 2 \& $level = $LOG\->level(); \& $level = $LOG\->level( $new_level ); .Ve .PP If \fB\f(CB$new_level\fB\fR given will change current log level. This is same as call \f(CW\*(C`config({ level=>$new_level })\*(C'\fR but much faster. .PP Return previous log level. .SS "ident" .IX Subsection "ident" .Vb 2 \& $ident = $LOG\->ident(); \& $ident = $LOG\->ident( $new_ident ); .Ve .PP If \fB\f(CB$new_ident\fB\fR given will change current syslog's ident. This is same as call \f(CW\*(C`config({ ident=>$new_ident })\*(C'\fR but much faster. .PP Return previous syslog's ident. .SS "\s-1ERR\s0" .IX Subsection "ERR" .SS "\s-1WARN\s0" .IX Subsection "WARN" .SS "\s-1NOTICE\s0" .IX Subsection "NOTICE" .SS "\s-1INFO\s0" .IX Subsection "INFO" .SS "\s-1DEBUG\s0" .IX Subsection "DEBUG" .Vb 10 \& $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 ) .Ve .PP Output \fB\f(CB$message\fB\fR to log using different log levels. .PP If \fB\f(CB$format\fB, \f(CB@list\fB\fR used instead of \fB\f(CB$message\fB\fR, then use \&\f(CW\*(C`sprintf($format, @list)\*(C'\fR to calculate log message. .PP If \fB\f(CB@list\fB\fR will contain \s-1CODEREF,\s0 they will be called (in \s-1LIST\s0 context) and returned values will be placed inside \fB\f(CB@list\fB\fR inplace of \s-1CODEREF.\s0 This can be used to avoid calculating log message (or it part) on disabled log levels \- these \s-1CODEREF\s0 will be executed only on enabled log levels. Example available in \*(L"\s-1SYNOPSIS\*(R"\s0. .PP If \fB\f(CB$message\fB\fR or items in \fB\f(CB@list\fB\fR will be Unicode strings, they will be converted to \s-1UTF8\s0 before sending to log. .PP Return nothing. Throw exception if fail to write message to log. .SH "OPTIONS" .IX Header "OPTIONS" Defaults for all options are: .PP .Vb 2 \& level => \*(AqDEBUG\*(Aq, \& prefix => q{}, \& \& type => \*(Aqfh\*(Aq, \& fh => \e*STDERR, \& \& # these will be used if you will call config({ type=>\*(Aqunix\*(Aq }) \& path => Sys::Syslog::_PATH_LOG() || \*(Aq/dev/log\*(Aq, \& facility => LOG_USER, \& add_timestamp => 1, \& add_hostname => 0, \& hostname => Sys::Hostname::hostname(), \& ident => ..., # calculated from $0 \& add_pid => 1, \& pid => $$, .Ve .IP "level" 4 .IX Item "level" Current log level. Possible values are: \&\f(CW\*(AqERR\*(Aq\fR, \f(CW\*(AqWARN\*(Aq\fR, \f(CW\*(AqNOTICE\*(Aq\fR, \f(CW\*(AqINFO\*(Aq\fR, \f(CW\*(AqDEBUG\*(Aq\fR. .Sp Only messages on current or higher levels will be sent to log. .IP "prefix" 4 .IX Item "prefix" String, which will be output at beginning of each log message. May contain these placeholders: .Sp .Vb 8 \& %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\*(Aqs function package (\*(Aqmain\*(Aq or \*(AqMy::Module\*(Aq) \& %F \- caller\*(Aqs function name \& %_ \- X spaces, where X is current stack depth \& %% \- % character .Ve .Sp Example output with prefix \f(CW\*(Aq%D %T [%L]%_%P::%F() \*(Aq\fR: .Sp .Vb 4 \& 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 .Ve .Sp If it will be Unicode string, it will be converted to \s-1UTF8.\s0 .IP "type" 4 .IX Item "type" Output type. Possible values are: \f(CW\*(Aqfh\*(Aq\fR (output to any already open filehandle) and \f(CW\*(Aqunix\*(Aq\fR (output to syslog using \s-1UNIX\s0 socket). .Sp When \fB{type}\fR set to \f(CW\*(Aqfh\*(Aq\fR you have to also set \fB{fh}\fR to any open filehandle (like \f(CW\*(C`\e*STDERR\*(C'\fR). .Sp When \fB{type}\fR set to \f(CW\*(Aqunix\*(Aq\fR you have to also set \fB{path}\fR to path to existing \s-1UNIX\s0 socket (typically it's \f(CW\*(Aq/dev/log\*(Aq\fR). .Sp Luckily, default values for both \fB{fh}\fR and \fB{path}\fR are already provided, so usually it's enough to just set \fB{type}\fR. .IP "fh" 4 .IX Item "fh" File handle to write log messages if \fB{type}\fR set to \f(CW\*(Aqfh\*(Aq\fR. .IP "path" 4 .IX Item "path" Syslog's \s-1UNIX\s0 socket path to write log messages if \fB{type}\fR set to \f(CW\*(Aqunix\*(Aq\fR. .IP "facility" 4 .IX Item "facility" Syslog's facility (see \*(L"Facilities\*(R" in Sys::Syslog for a list of well-known facilities). .Sp This module doesn't export any constants, so if you wanna change it from default \&\s-1LOG_USER\s0 value, you should import facility constants from Sys::Syslog module. Example available in \*(L"\s-1SYNOPSIS\*(R"\s0. .IP "add_timestamp" 4 .IX Item "add_timestamp" If \s-1TRUE\s0 will include timestamp in syslog messages. .IP "add_hostname" 4 .IX Item "add_hostname" If \s-1TRUE\s0 will include hostname in syslog messages. .IP "hostname" 4 .IX Item "hostname" Host name which will be included in syslog messages if \fB{add_hostname}\fR is \s-1TRUE.\s0 .IP "ident" 4 .IX Item "ident" Syslog's ident (application name) field. .Sp If it will be Unicode string, it will be converted to \s-1UTF8.\s0 Using non-ASCII \s-1ALPHANUMERIC\s0 ident isn't allowed by \s-1RFC,\s0 but usually works. .IP "add_pid" 4 .IX Item "add_pid" If \s-1TRUE\s0 will include \s-1PID\s0 in syslog messages. .IP "pid" 4 .IX Item "pid" \&\s-1PID\s0 which will be included in syslog messages if \fB{add_pid}\fR is \s-1TRUE.\s0 .SH "SPEED HINTS" .IX Header "SPEED HINTS" Empty prefix is fastest. Prefixes \f(CW%L\fR, \f(CW%P\fR and \f(CW\*(C`%%\*(C'\fR are fast enough, \&\f(CW%D\fR and \f(CW%T\fR has average speed, \f(CW%S\fR, \f(CW%F\fR and \f(CW%_\fR are slowest. .PP Output to file is about 4 times faster than to syslog. .PP Calling log with single parameter is faster than with many parameters (because in second case \fBsprintf()\fR have to be used). .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "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. .PP .PP .Vb 1 \& git clone https://github.com/powerman/perl\-Log\-Fast.git .Ve .SS "Resources" .IX Subsection "Resources" .IP "\(bu" 4 MetaCPAN Search .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Testers Matrix .Sp .IP "\(bu" 4 \&\s-1CPANTS: A CPAN\s0 Testing Service (Kwalitee) .Sp .SH "AUTHOR" .IX Header "AUTHOR" Alex Efros .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2010\- by Alex Efros . .PP This is free software, licensed under: .PP .Vb 1 \& The MIT (X11) License .Ve