—

              
package Log::ger::Manual::Tutorial::300_Level;
# AUTHORITY
# DATE
our $DIST = 'Log-ger-Manual'; # DIST
# VERSION
1;
# ABSTRACT: Logging levels
__END__
HideShow 152 lines of Pod
=pod
=encoding UTF-8
=head1 NAME
Log::ger::Manual::Tutorial::300_Level - Logging levels
=head1 VERSION
version 0.040.000
=head1 DESCRIPTION
=over
=back
=head1 WHAT IS LOGGING LEVEL?
When logging a message, you can choose from one of the several available levels:
 log_info("This is just an informational message");
 log_warn("This is a warning, you have been warned");
 log_error("This is an error!");
 log_fatal("This is a serious error!!! I can't continue"); exit;
Level signifies the importance, urgency, and/or severity of the message. One of
the main ways the log messages are filtered is by level.
=head1 WHICH LEVEL SHOULD I USE FOR WHICH PURPOSE?
Log::ger comes with the following standard levels, sorted from the most
important/severe to the least. The number in parentheses is the numeric
representation for that level:
 fatal (10)
 error (20)
 warn (30)
 info (40)
 debug (50)
 trace (60)
Aside from the above, there are also these category aliases:
 off (0)
 warning (30)
Aliases don't get their own logging subroutines/methods (so there's no
C<log_off> or C<log_warning>, only C<log_warn>), but they are recognized e.g.
when you feed one to C<Log::ger::Util::set_level()>.
There is no absolute set of rules on which level you should use for which
purposes. The most important thing is to be consistent. Here are some links you
can read:
=over
=item * Choosing a Log Level (L<Log::Any>)
L<http://blogs.perl.org/users/preaction/2017/03/choosing-a-log-level.html>
=item * When to use the different log levels?
L<https://stackoverflow.com/questions/2031163/when-to-use-the-different-log-levels>
=back
I personally use this set of rules:
=over
=item * C<info|warn|error|fatal> vs C<debug|trace>
C<info>, C<warn> and higher are to be shown to end users of application
(non-developers) while C<debug> and C<trace> are meant only for developers. This
means, C<debug> and C<trace> messages tend to be more technical and precise.
=item * C<info> only for verbose output
C<info> should only be shown when users specify increased verbosity, e.g. via
command-line option C<--verbose>.
=item * C<warn>
C<warn> is for informing that there are some abnormality but not necessarily an
error.
=item * C<error>
C<error> is for error condition (obviously) but the program can continue.
=item * C<fatal>
C<fatal> is for a serious error that renders the program unable to continue.
=item * C<debug> vs C<trace>
Between C<debug> and C<trace>: C<trace> is usually for dumping internal data
structures or informing the flow of program execution (entering/leaving a
subroutine), for everything else developer-related, use C<debug>.
=back
=head1 SETTING LEVEL
At the start of program, the level is set to C<warn>. This means messages logged
by C<log_info()> or C<log_debug()> by default won't be shown even after we set
an output.
To change level, you can use:
 use Log::ger::Util;
 Log::ger::Util::set_level("info"); # or ...
 Log::ger::Util::set_level(40);
C<set_level()> will die if you feed it an unknown string level.
Normally you will only need to do this in an application, not in modules. One
piece of advice is to allow user to change the level without her having to
modify the source code, for example via environment variable and/or command-line
option. An application framework like L<Perinci::CmdLine> takes care of this for
you, so you don't need to do C<set_level> manually at all.
Another module you can use for this purpose is L<Log::ger::Level::FromEnv>. This
module detects some environment variables (like C<LOG_LEVEL=debug>, or
C<TRACE=1>) then set the logging level according to it.
=head1 CUSTOM LEVELS
A more complex program might want to customize (increase the number of) levels.
Log::ger allows you to do this. Basically all you have to do is set
C<%Log::ger::Levels>, preferably before intializing logging for any package
using C<use Log::ger>.
Some modules provide levels that mimic those in other frameworks, e.g.
L<Log::ger::Level::Like::LogAny> or other C<Log::ger::Level::Like::*> modules.
=head1 AUTHOR
perlancar <perlancar@cpan.org>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2022, 2020, 2019, 2018, 2017 by perlancar <perlancar@cpan.org>.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut