| 1 |
NAME |
| 2 |
Log::ger - A lightweight, flexible logging framework |
| 3 |
|
| 4 |
VERSION |
| 5 |
version 0.042 |
| 6 |
|
| 7 |
SYNOPSIS |
| 8 |
Producing logs |
| 9 |
In your module (producer): |
| 10 |
|
| 11 |
package MyModule; |
| 12 |
|
| 13 |
# this will install some logger routines. by default: log_trace, log_debug, |
| 14 |
# log_info, log_warn, log_error, and log_fatal. level checker routines are also |
| 15 |
# installed: log_is_trace, log_is_debug, and so on. |
| 16 |
use Log::ger; |
| 17 |
|
| 18 |
sub foo { |
| 19 |
... |
| 20 |
# produce some logs. no need to configure output or level. by default |
| 21 |
# output goes nowhere. |
| 22 |
log_error "an error occured: %03d - %s", $errcode, $errmsg; |
| 23 |
... |
| 24 |
|
| 25 |
# the logging routines (log_*) can automatically dump data structures |
| 26 |
log_debug "http response: %s", $http; |
| 27 |
|
| 28 |
# log_fatal does not die by default, if you want to then die() explicitly. |
| 29 |
# but there are plugins that let you do this or provide log_die etc. |
| 30 |
if (blah) { log_fatal "..."; die } |
| 31 |
|
| 32 |
# use the level checker routines (log_is_*) to avoid doing unnecessary |
| 33 |
# heavy calculation |
| 34 |
if (log_is_trace) { |
| 35 |
my $res = some_heavy_calculation(); |
| 36 |
log_trace "The result is %s", $res; |
| 37 |
} |
| 38 |
|
| 39 |
} |
| 40 |
1; |
| 41 |
|
| 42 |
Consuming logs |
| 43 |
Choosing an output |
| 44 |
In your application (consumer/listener): |
| 45 |
|
| 46 |
use MyModule; |
| 47 |
use Log::ger::Output 'Screen'; # configure output |
| 48 |
# level is by default 'warn' |
| 49 |
foo(); # the error message is shown, but debug/trace messages are not. |
| 50 |
|
| 51 |
Choosing multiple outputs |
| 52 |
Instead of screen, you can output to multiple outputs (including |
| 53 |
multiple files): |
| 54 |
|
| 55 |
use Log::ger::Output 'Composite' => ( |
| 56 |
outputs => { |
| 57 |
Screen => {}, |
| 58 |
File => [ |
| 59 |
{conf=>{path=>'/path/to/app.log'}}, |
| 60 |
... |
| 61 |
], |
| 62 |
... |
| 63 |
}, |
| 64 |
); |
| 65 |
|
| 66 |
See Log::ger::Manual::Tutorial::481_Output_Composite for more examples. |
| 67 |
|
| 68 |
There is also Log::ger::App that wraps this in a simple interface so you |
| 69 |
just need to do: |
| 70 |
|
| 71 |
# In your application or script: |
| 72 |
use Log::ger::App; |
| 73 |
use MyModule; |
| 74 |
|
| 75 |
Choosing level |
| 76 |
One way to set level: |
| 77 |
|
| 78 |
use Log::ger::Util; |
| 79 |
Log::ger::Util::set_level('debug'); # be more verbose |
| 80 |
foo(); # the error message as well as debug message are now shown, but the trace is not |
| 81 |
|
| 82 |
There are better ways, e.g. letting users configure log level via |
| 83 |
configuration file or command-line option. See |
| 84 |
Log::ger::Manual::Tutorial::300_Level for more details. |
| 85 |
|
| 86 |
DESCRIPTION |
| 87 |
Log::ger is yet another logging framework with the following features: |
| 88 |
|
| 89 |
* Separation of producers and consumers/listeners |
| 90 |
|
| 91 |
Like Log::Any, this offers a very easy way for modules to produce |
| 92 |
some logs without having to configure anything. Configuring output, |
| 93 |
level, etc can be done in the application as log |
| 94 |
consumers/listeners. To read more about this, see the documentation |
| 95 |
of Log::Any or Log::ger::Manual (but nevertheless see |
| 96 |
Log::ger::Manual on why you might prefer Log::ger to Log::Any). |
| 97 |
|
| 98 |
* Lightweight and fast |
| 99 |
|
| 100 |
Slim distribution. No non-core dependencies, extra functionalities |
| 101 |
are provided in separate distributions to be pulled as needed. |
| 102 |
|
| 103 |
Low startup overhead. Only ~0.5-1ms. For comparison, strict |
| 104 |
~0.2-0.5ms, warnings ~2ms, Log::Any (v0.15) ~2-3ms, Log::Any |
| 105 |
(v1.049) ~8-10ms, Log::Log4perl ~35ms. This is measured on a |
| 106 |
2014-2015 PC and before doing any output configuration. I strive to |
| 107 |
make "use Log::ger;" statement to be roughly as light as "use |
| 108 |
strict;" or "use warnings;" so the impact of adding the statement is |
| 109 |
really minimal and you can just add logging without much thought to |
| 110 |
most of your modules. This is important to me because I want logging |
| 111 |
to be pervasive. |
| 112 |
|
| 113 |
To test for yourself, try e.g. with bencher-code: |
| 114 |
|
| 115 |
% bencher-code 'use Log::ger' 'use Log::Any' --startup |
| 116 |
|
| 117 |
Fast. Low null-/stealth-logging overhead, about 1.5x faster than |
| 118 |
Log::Any, 3x faster than Log4perl, 5x faster than Log::Fast, ~40x |
| 119 |
faster than Log::Contextual, and ~100x faster than Log::Dispatch. |
| 120 |
|
| 121 |
For more benchmarks, see Bencher::Scenarios::Log::ger. |
| 122 |
|
| 123 |
Conditional compilation. There is a plugin to optimize away unneeded |
| 124 |
logging statements, like assertion/conditional compilation, so they |
| 125 |
have zero runtime performance cost. See Log::ger::Plugin::OptAway. |
| 126 |
|
| 127 |
Being lightweight means the module can be used more universally, |
| 128 |
from CLI to long-running daemons to inside routines with tight |
| 129 |
loops. |
| 130 |
|
| 131 |
* Flexible |
| 132 |
|
| 133 |
Customizable levels and routine/method names. Can be used in a |
| 134 |
procedural or OO style. Log::ger can mimic the interface of |
| 135 |
Log::Any, Log::Contextual, Log::Log4perl, or some other popular |
| 136 |
logging frameworks, to ease migration or adjust with your personal |
| 137 |
style. |
| 138 |
|
| 139 |
Per-package settings. Each importer package can use its own |
| 140 |
format/layout, output. For example, a module that is migrated from |
| 141 |
Log::Any uses Log::Any-style logging, while another uses native |
| 142 |
Log::ger style, and yet some other uses block formatting like |
| 143 |
Log::Contextual. This eases code migration and teamwork. Each module |
| 144 |
author can preserve her own logging style, if wanted, and all the |
| 145 |
modules still use the same framework. |
| 146 |
|
| 147 |
Dynamic. Outputs and levels can be changed anytime during run-time |
| 148 |
and logger routines will be updated automatically. This is useful in |
| 149 |
situation like a long-running server application: you can turn on |
| 150 |
tracing logs temporarily to debug problems, then turn them off |
| 151 |
again, without restarting your server. |
| 152 |
|
| 153 |
Interoperability. There are modules to interop with Log::Any, either |
| 154 |
consume Log::Any logs (see Log::Any::Adapter::LogGer) or produce |
| 155 |
logs to be consumed by Log::Any (see Log::ger::Output::LogAny). |
| 156 |
|
| 157 |
Many output modules and plugins. See "Log::ger::Output::*", |
| 158 |
"Log::ger::Format::*", "Log::ger::Layout::*", "Log::ger::Plugin::*". |
| 159 |
Writing an output module in Log::ger is easier than writing a |
| 160 |
Log::Any::Adapter::*. |
| 161 |
|
| 162 |
For more documentation, start with Log::ger::Manual. |
| 163 |
|
| 164 |
SEE ALSO |
| 165 |
Some other popular logging frameworks: Log::Any, Log::Contextual, |
| 166 |
Log::Log4perl, Log::Dispatch, Log::Dispatchouli. |
| 167 |
|
| 168 |
If you still prefer debugging using the good old print(), there's |
| 169 |
Debug::Print. |
| 170 |
|
| 171 |
AUTHOR |
| 172 |
perlancar <[email protected]> |
| 173 |
|
| 174 |
COPYRIGHT AND LICENSE |
| 175 |
This software is copyright (c) 2023, 2022, 2020, 2019, 2018, 2017 by |
| 176 |
perlancar <[email protected]>. |
| 177 |
|
| 178 |
This is free software; you can redistribute it and/or modify it under |
| 179 |
the same terms as the Perl 5 programming language system itself. |
| 180 |
|