1Log::ger(3)           User Contributed Perl Documentation          Log::ger(3)
2
3
4

NAME

6       Log::ger - A lightweight, flexible logging framework
7

VERSION

9       version 0.031
10

SYNOPSIS

12   Producing logs
13       In your module (producer):
14
15        package Foo;
16        use Log::ger; # will import some logging methods e.g. log_warn, log_error
17
18        sub foo {
19            ...
20            # produce some logs. no need to configure output or level.
21            log_error "an error occured: %03d - %s", $errcode, $errmsg;
22            ...
23            log_debug "http response: %s", $http; # automatic dumping of data
24        }
25        1;
26
27   Consuming logs
28       Choosing an output
29
30       In your application (consumer/listener):
31
32        use Foo;
33        use Log::ger::Output 'Screen'; # configure output
34        # level is by default 'warn'
35        foo(); # the error message is shown, but debug message is not.
36
37       Choosing multiple outputs
38
39       Instead of screen, you can output to multiple outputs (including
40       multiple files):
41
42        use Log::ger::Output 'Composite' => (
43            outputs => {
44                Screen => {},
45                File   => [
46                    {conf=>{path=>'/path/to/app.log'}},
47                    ...
48                ],
49                ...
50            },
51        );
52
53       See Log::ger::Manual::Tutorial::481_Output_Composite for more examples.
54
55       Choosing level
56
57       One way to set level:
58
59        use Log::ger::Util;
60        Log::ger::Util::set_level('debug'); # be more verbose
61        foo(); # the error message as well as debug message are now shown
62
63       There are better ways, e.g. letting users configure log level via
64       configuration file or command-line option. See
65       Log::ger::Manual::Tutorial::300_Level for more details.
66

DESCRIPTION

68       Log::ger is yet another logging framework with the following features:
69
70       ·   Separation of producers and consumers/listeners
71
72           Like Log::Any, this offers a very easy way for modules to produce
73           some logs without having to configure anything. Configuring output,
74           level, etc can be done in the application as log
75           consumers/listeners. To read more about this, see the documentation
76           of Log::Any or Log::ger::Manual (but nevertheless see
77           Log::ger::Manual on why you might prefer Log::ger to Log::Any).
78
79       ·   Lightweight and fast
80
81           Slim distribution. No non-core dependencies, extra functionalities
82           are provided in separate distributions to be pulled as needed.
83
84           Low startup overhead. Only ~0.5-1ms. For comparison, strict
85           ~0.2-0.5ms, warnings ~2ms, Log::Any (v0.15) ~2-3ms, Log::Any
86           (v1.049) ~8-10ms, Log::Log4perl ~35ms. This is measured on a
87           2014-2015 PC and before doing any output configuration. I strive to
88           make "use Log::ger;" statement to be roughly as light as "use
89           strict;" or "use warnings;" so the impact of adding the statement
90           is really minimal and you can just add logging without much thought
91           to most of your modules. This is important to me because I want
92           logging to be pervasive.
93
94           To test for yourself, try e.g. with bencher-code:
95
96            % bencher-code 'use Log::ger' 'use Log::Any' --startup
97
98           Fast. Low null-/stealth-logging overhead, about 1.5x faster than
99           Log::Any, 3x faster than Log4perl, 5x faster than Log::Fast, ~40x
100           faster than Log::Contextual, and ~100x faster than Log::Dispatch.
101
102           For more benchmarks, see Bencher::Scenarios::LogGer.
103
104           Conditional compilation. There is a plugin to optimize away
105           unneeded logging statements, like assertion/conditional
106           compilation, so they have zero runtime performance cost. See
107           Log::ger::Plugin::OptAway.
108
109           Being lightweight means the module can be used more universally,
110           from CLI to long-running daemons to inside routines with tight
111           loops.
112
113       ·   Flexible
114
115           Customizable levels and routine/method names. Can be used in a
116           procedural or OO style. Log::ger can mimic the interface of
117           Log::Any, Log::Contextual, Log::Log4perl, or some other popular
118           logging frameworks, to ease migration or adjust with your personal
119           style.
120
121           Per-package settings. Each importer package can use its own
122           format/layout, output. For example, a module that is migrated from
123           Log::Any uses Log::Any-style logging, while another uses native
124           Log::ger style, and yet some other uses block formatting like
125           Log::Contextual. This eases code migration and teamwork. Each
126           module author can preserve her own logging style, if wanted, and
127           all the modules still use the same framework.
128
129           Dynamic. Outputs and levels can be changed anytime during run-time
130           and logging routines will be updated automatically. This is useful
131           in situation like a long-running server application: you can turn
132           on tracing logs temporarily to debug problems, then turn them off
133           again, without restarting your server.
134
135           Interoperability. There are modules to interop with Log::Any,
136           either consume Log::Any logs (see Log::Any::Adapter::LogGer) or
137           produce logs to be consumed by Log::Any (see
138           Log::ger::Output::LogAny).
139
140           Many output modules and plugins. See "Log::ger::Output::*",
141           "Log::ger::Format::*", "Log::ger::Layout::*",
142           "Log::ger::Plugin::*". Writing an output module in Log::ger is
143           easier than writing a Log::Any::Adapter::*.
144
145       For more documentation, start with Log::ger::Manual.
146

SEE ALSO

148       Some other popular logging frameworks: Log::Any, Log::Contextual,
149       Log::Log4perl, Log::Dispatch, Log::Dispatchouli.
150
151       If you still prefer debugging using the good old "print()", there's
152       Debug::Print.
153

AUTHOR

155       perlancar <perlancar@cpan.org>
156
158       This software is copyright (c) 2020, 2019, 2018, 2017 by
159       perlancar@cpan.org.
160
161       This is free software; you can redistribute it and/or modify it under
162       the same terms as the Perl 5 programming language system itself.
163
164
165
166perl v5.30.1                      2020-03-04                       Log::ger(3)
Impressum