Log::ger(3pm)

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.040
10

SYNOPSIS

12   Producing logs
13       In your module (producer):
14
15        package MyModule;
16
17        # this will install some logger routines. by default: log_trace, log_debug,
18        # log_info, log_warn, log_error, and log_fatal. level checker routines are also
19        # installed: log_is_trace, log_is_debug, and so on.
20        use Log::ger;
21
22        sub foo {
23            ...
24            # produce some logs. no need to configure output or level. by default
25            # output goes nowhere.
26            log_error "an error occured: %03d - %s", $errcode, $errmsg;
27            ...
28
29            # the logging routines (log_*) can automatically dump of data structure
30            log_debug "http response: %s", $http;
31
32            # log_fatal does not die by default, if you want to then die() explicitly.
33            # but there are plugins that let you do this or provide log_die etc.
34            if (blah) { log_fatal "..."; die }
35
36            # use the level checker routines (log_is_*) to avoid doing unnecessary
37            # heavy calculation
38            if (log_is_trace) {
39                my $res = some_heavy_calculation();
40                log_trace "The result is %s", $res;
41            }
42
43        }
44        1;
45
46   Consuming logs
47       Choosing an output
48
49       In your application (consumer/listener):
50
51        use MyModule;
52        use Log::ger::Output 'Screen'; # configure output
53        # level is by default 'warn'
54        foo(); # the error message is shown, but debug/trace messages are not.
55
56       Choosing multiple outputs
57
58       Instead of screen, you can output to multiple outputs (including
59       multiple files):
60
61        use Log::ger::Output 'Composite' => (
62            outputs => {
63                Screen => {},
64                File   => [
65                    {conf=>{path=>'/path/to/app.log'}},
66                    ...
67                ],
68                ...
69            },
70        );
71
72       See Log::ger::Manual::Tutorial::481_Output_Composite for more examples.
73
74       There is also Log::ger::App that wraps this in a simple interface so
75       you just need to do:
76
77        # In your application or script:
78        use Log::ger::App;
79        use MyModule;
80
81       Choosing level
82
83       One way to set level:
84
85        use Log::ger::Util;
86        Log::ger::Util::set_level('debug'); # be more verbose
87        foo(); # the error message as well as debug message are now shown, but the trace is not
88
89       There are better ways, e.g. letting users configure log level via
90       configuration file or command-line option. See
91       Log::ger::Manual::Tutorial::300_Level for more details.
92

DESCRIPTION

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

AUTHOR

181       perlancar <perlancar@cpan.org>
182

COPYRIGHT AND LICENSE

184       This software is copyright (c) 2022, 2020, 2019, 2018, 2017 by
185       perlancar <perlancar@cpan.org>.
186
187       This is free software; you can redistribute it and/or modify it under
188       the same terms as the Perl 5 programming language system itself.
189
190
191
192perl v5.36.0                      2023-01-20                       Log::ger(3)

NAME

VERSION

SYNOPSIS

DESCRIPTION

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE