| 1 |
NAME |
| 2 |
|
| 3 |
Log::Fast - Fast and flexible logger |
| 4 |
|
| 5 |
VERSION |
| 6 |
|
| 7 |
This document describes Log::Fast version v2.0.1 |
| 8 |
|
| 9 |
SYNOPSIS |
| 10 |
|
| 11 |
use Log::Fast; |
| 12 |
|
| 13 |
$LOG = Log::Fast->global(); |
| 14 |
$LOG = Log::Fast->new({ |
| 15 |
level => 'WARN', |
| 16 |
prefix => '%D %T [%L] ', |
| 17 |
type => 'fh', |
| 18 |
fh => \*STDOUT, |
| 19 |
}); |
| 20 |
|
| 21 |
use Sys::Syslog qw( LOG_DAEMON ); |
| 22 |
$LOG->config({ |
| 23 |
prefix => '', |
| 24 |
type => 'unix', |
| 25 |
path => '/dev/log', |
| 26 |
facility => LOG_DAEMON, |
| 27 |
add_timestamp => 1, |
| 28 |
add_hostname => 1, |
| 29 |
hostname => 'somehost', |
| 30 |
ident => 'someapp', |
| 31 |
add_pid => 1, |
| 32 |
pid => $$, |
| 33 |
}); |
| 34 |
|
| 35 |
$LOG->ident('anotherapp'); |
| 36 |
$LOG->level('INFO'); |
| 37 |
|
| 38 |
$LOG->ERR('Some error'); |
| 39 |
$LOG->WARN('Some warning'); |
| 40 |
$LOG->NOTICE('user %s logged in', $user); |
| 41 |
$LOG->INFO('data loaded'); |
| 42 |
$LOG->DEBUG('user %s have %d things', $user, sub { |
| 43 |
return SlowOperation_GetAmountOfThingsFor($user); |
| 44 |
}); |
| 45 |
|
| 46 |
DESCRIPTION |
| 47 |
|
| 48 |
This is very fast logger, designed for use in applications with |
| 49 |
thousands high-level events/operations per second (like network servers |
| 50 |
with thousands clients or web spiders which download hundreds url per |
| 51 |
second). |
| 52 |
|
| 53 |
For example, on Core2Duo sending about 5000 messages to log on enabled |
| 54 |
log levels or 20000 messages on disabled log levels in one second will |
| 55 |
slow down your application only by 2-3%. |
| 56 |
|
| 57 |
Comparing to some other CPAN modules, this one (in average): faster |
| 58 |
than Log::Dispatch in about 45 times, faster than Log::Handler in about |
| 59 |
15 times, faster than Sys::Syslog in about 7 times, and slower than |
| 60 |
Log::Syslog::Fast in about 2 times. |
| 61 |
|
| 62 |
FEATURES |
| 63 |
|
| 64 |
* Global and local logger objects |
| 65 |
|
| 66 |
* Output to any open filehandle or local syslog |
| 67 |
|
| 68 |
* 5 log levels: ERR, WARN, NOTICE, INFO, DEBUG |
| 69 |
|
| 70 |
* Configurable prefix (log level, date/time, caller function name) |
| 71 |
|
| 72 |
* sprintf() support |
| 73 |
|
| 74 |
* Unicode support (UTF8) |
| 75 |
|
| 76 |
* Can avoid calculating log message content on disabled log levels |
| 77 |
|
| 78 |
INTERFACE |
| 79 |
|
| 80 |
global |
| 81 |
|
| 82 |
$LOG = Log::Fast->global(); |
| 83 |
|
| 84 |
When called first time will create global log object using default |
| 85 |
options (you can reconfigure it using config() later). |
| 86 |
|
| 87 |
Global log object is useful if your application consists of several |
| 88 |
independent modules which should share same logging options configured |
| 89 |
outside of these modules. In this case all these modules should use |
| 90 |
same global() log object instead of creating new() independent log |
| 91 |
objects in each module. |
| 92 |
|
| 93 |
Return global log object. |
| 94 |
|
| 95 |
new |
| 96 |
|
| 97 |
$LOG = Log::Fast->new(); |
| 98 |
$LOG = Log::Fast->new( \%opt ); |
| 99 |
|
| 100 |
Create new log object, configured using defaults and user-provided |
| 101 |
options, if any. |
| 102 |
|
| 103 |
Return created log object. |
| 104 |
|
| 105 |
config |
| 106 |
|
| 107 |
$LOG->config( \%opt ); |
| 108 |
|
| 109 |
Reconfigure log object. Any options (see "OPTIONS") can be changed at |
| 110 |
any time, including changing output {type} or setting options useless |
| 111 |
with current output type (new values for these options will be used |
| 112 |
later, if output type will be changed). |
| 113 |
|
| 114 |
If you need to change only log {level} or syslog's {ident} you should |
| 115 |
use level() or ident() methods because they are much faster than more |
| 116 |
general config(). |
| 117 |
|
| 118 |
Return nothing. Throw exception if unable to connect to syslog. |
| 119 |
|
| 120 |
level |
| 121 |
|
| 122 |
$level = $LOG->level(); |
| 123 |
$level = $LOG->level( $new_level ); |
| 124 |
|
| 125 |
If $new_level given will change current log level. This is same as call |
| 126 |
config({ level=>$new_level }) but much faster. |
| 127 |
|
| 128 |
Return previous log level. |
| 129 |
|
| 130 |
ident |
| 131 |
|
| 132 |
$ident = $LOG->ident(); |
| 133 |
$ident = $LOG->ident( $new_ident ); |
| 134 |
|
| 135 |
If $new_ident given will change current syslog's ident. This is same as |
| 136 |
call config({ ident=>$new_ident }) but much faster. |
| 137 |
|
| 138 |
Return previous syslog's ident. |
| 139 |
|
| 140 |
ERR |
| 141 |
|
| 142 |
WARN |
| 143 |
|
| 144 |
NOTICE |
| 145 |
|
| 146 |
INFO |
| 147 |
|
| 148 |
DEBUG |
| 149 |
|
| 150 |
$LOG->ERR( $message ) |
| 151 |
$LOG->ERR( $format, @list ) |
| 152 |
$LOG->WARN( $message ) |
| 153 |
$LOG->WARN( $format, @list ) |
| 154 |
$LOG->NOTICE( $message ) |
| 155 |
$LOG->NOTICE( $format, @list ) |
| 156 |
$LOG->INFO( $message ) |
| 157 |
$LOG->INFO( $format, @list ) |
| 158 |
$LOG->DEBUG( $message ) |
| 159 |
$LOG->DEBUG( $format, @list ) |
| 160 |
|
| 161 |
Output $message to log using different log levels. |
| 162 |
|
| 163 |
If $format, @list used instead of $message, then use sprintf($format, |
| 164 |
@list) to calculate log message. |
| 165 |
|
| 166 |
If @list will contain CODEREF, they will be called (in LIST context) |
| 167 |
and returned values will be placed inside @list inplace of CODEREF. |
| 168 |
This can be used to avoid calculating log message (or it part) on |
| 169 |
disabled log levels - these CODEREF will be executed only on enabled |
| 170 |
log levels. Example available in "SYNOPSIS". |
| 171 |
|
| 172 |
If $message or items in @list will be Unicode strings, they will be |
| 173 |
converted to UTF8 before sending to log. |
| 174 |
|
| 175 |
Return nothing. Throw exception if fail to write message to log. |
| 176 |
|
| 177 |
OPTIONS |
| 178 |
|
| 179 |
Defaults for all options are: |
| 180 |
|
| 181 |
level => 'DEBUG', |
| 182 |
prefix => q{}, |
| 183 |
|
| 184 |
type => 'fh', |
| 185 |
fh => \*STDERR, |
| 186 |
|
| 187 |
# these will be used if you will call config({ type=>'unix' }) |
| 188 |
path => Sys::Syslog::_PATH_LOG() || '/dev/log', |
| 189 |
facility => LOG_USER, |
| 190 |
add_timestamp => 1, |
| 191 |
add_hostname => 0, |
| 192 |
hostname => Sys::Hostname::hostname(), |
| 193 |
ident => ..., # calculated from $0 |
| 194 |
add_pid => 1, |
| 195 |
pid => $$, |
| 196 |
|
| 197 |
level |
| 198 |
|
| 199 |
Current log level. Possible values are: 'ERR', 'WARN', 'NOTICE', |
| 200 |
'INFO', 'DEBUG'. |
| 201 |
|
| 202 |
Only messages on current or higher levels will be sent to log. |
| 203 |
|
| 204 |
prefix |
| 205 |
|
| 206 |
String, which will be output at beginning of each log message. May |
| 207 |
contain these placeholders: |
| 208 |
|
| 209 |
%L - log level of current message |
| 210 |
%S - hi-resolution time (seconds.microseconds) |
| 211 |
%D - current date in format YYYY-MM-DD |
| 212 |
%T - current time in format HH:MM:SS |
| 213 |
%P - caller's function package ('main' or 'My::Module') |
| 214 |
%F - caller's function name |
| 215 |
%_ - X spaces, where X is current stack depth |
| 216 |
%% - % character |
| 217 |
|
| 218 |
Example output with prefix '%D %T [%L]%_%P::%F() ': |
| 219 |
|
| 220 |
2010-11-17 18:06:20 [INFO] main::() something from main script |
| 221 |
2010-11-17 18:06:53 [INFO] main::a() something from a |
| 222 |
2010-11-17 18:09:09 [INFO] main::b2() something from b1->b2 |
| 223 |
2010-11-17 18:06:56 [INFO] main::c() something from c |
| 224 |
|
| 225 |
If it will be Unicode string, it will be converted to UTF8. |
| 226 |
|
| 227 |
type |
| 228 |
|
| 229 |
Output type. Possible values are: 'fh' (output to any already open |
| 230 |
filehandle) and 'unix' (output to syslog using UNIX socket). |
| 231 |
|
| 232 |
When {type} set to 'fh' you have to also set {fh} to any open |
| 233 |
filehandle (like \*STDERR). |
| 234 |
|
| 235 |
When {type} set to 'unix' you have to also set {path} to path to |
| 236 |
existing UNIX socket (typically it's '/dev/log'). |
| 237 |
|
| 238 |
Luckily, default values for both {fh} and {path} are already |
| 239 |
provided, so usually it's enough to just set {type}. |
| 240 |
|
| 241 |
fh |
| 242 |
|
| 243 |
File handle to write log messages if {type} set to 'fh'. |
| 244 |
|
| 245 |
path |
| 246 |
|
| 247 |
Syslog's UNIX socket path to write log messages if {type} set to |
| 248 |
'unix'. |
| 249 |
|
| 250 |
facility |
| 251 |
|
| 252 |
Syslog's facility (see "Facilities" in Sys::Syslog for a list of |
| 253 |
well-known facilities). |
| 254 |
|
| 255 |
This module doesn't export any constants, so if you wanna change it |
| 256 |
from default LOG_USER value, you should import facility constants |
| 257 |
from Sys::Syslog module. Example available in "SYNOPSIS". |
| 258 |
|
| 259 |
add_timestamp |
| 260 |
|
| 261 |
If TRUE will include timestamp in syslog messages. |
| 262 |
|
| 263 |
add_hostname |
| 264 |
|
| 265 |
If TRUE will include hostname in syslog messages. |
| 266 |
|
| 267 |
hostname |
| 268 |
|
| 269 |
Host name which will be included in syslog messages if {add_hostname} |
| 270 |
is TRUE. |
| 271 |
|
| 272 |
ident |
| 273 |
|
| 274 |
Syslog's ident (application name) field. |
| 275 |
|
| 276 |
If it will be Unicode string, it will be converted to UTF8. Using |
| 277 |
non-ASCII ALPHANUMERIC ident isn't allowed by RFC, but usually works. |
| 278 |
|
| 279 |
add_pid |
| 280 |
|
| 281 |
If TRUE will include PID in syslog messages. |
| 282 |
|
| 283 |
pid |
| 284 |
|
| 285 |
PID which will be included in syslog messages if {add_pid} is TRUE. |
| 286 |
|
| 287 |
SPEED HINTS |
| 288 |
|
| 289 |
Empty prefix is fastest. Prefixes %L, %P and %% are fast enough, %D and |
| 290 |
%T has average speed, %S, %F and %_ are slowest. |
| 291 |
|
| 292 |
Output to file is about 4 times faster than to syslog. |
| 293 |
|
| 294 |
Calling log with single parameter is faster than with many parameters |
| 295 |
(because in second case sprintf() have to be used). |
| 296 |
|
| 297 |
SUPPORT |
| 298 |
|
| 299 |
Bugs / Feature Requests |
| 300 |
|
| 301 |
Please report any bugs or feature requests through the issue tracker at |
| 302 |
https://github.com/powerman/perl-Log-Fast/issues. You will be notified |
| 303 |
automatically of any progress on your issue. |
| 304 |
|
| 305 |
Source Code |
| 306 |
|
| 307 |
This is open source software. The code repository is available for |
| 308 |
public review and contribution under the terms of the license. Feel |
| 309 |
free to fork the repository and submit pull requests. |
| 310 |
|
| 311 |
https://github.com/powerman/perl-Log-Fast |
| 312 |
|
| 313 |
git clone https://github.com/powerman/perl-Log-Fast.git |
| 314 |
|
| 315 |
Resources |
| 316 |
|
| 317 |
* MetaCPAN Search |
| 318 |
|
| 319 |
https://metacpan.org/search?q=Log-Fast |
| 320 |
|
| 321 |
* CPAN Ratings |
| 322 |
|
| 323 |
http://cpanratings.perl.org/dist/Log-Fast |
| 324 |
|
| 325 |
* AnnoCPAN: Annotated CPAN documentation |
| 326 |
|
| 327 |
http://annocpan.org/dist/Log-Fast |
| 328 |
|
| 329 |
* CPAN Testers Matrix |
| 330 |
|
| 331 |
http://matrix.cpantesters.org/?dist=Log-Fast |
| 332 |
|
| 333 |
* CPANTS: A CPAN Testing Service (Kwalitee) |
| 334 |
|
| 335 |
http://cpants.cpanauthors.org/dist/Log-Fast |
| 336 |
|
| 337 |
AUTHOR |
| 338 |
|
| 339 |
Alex Efros <[email protected]> |
| 340 |
|
| 341 |
COPYRIGHT AND LICENSE |
| 342 |
|
| 343 |
This software is Copyright (c) 2010- by Alex Efros <[email protected]>. |
| 344 |
|
| 345 |
This is free software, licensed under: |
| 346 |
|
| 347 |
The MIT (X11) License |
| 348 |
|