Debian Codegraph @

README

raw
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