Log::ger::Manual::Tutorial::300_Level - Logging levels
version 0.028.006
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.
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 log_off or log_warning, only log_warn), but they are recognized e.g. when you feed one to Log::ger::Util::set_level().
log_off
log_warning
log_warn
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:
Choosing a Log Level (Log::Any)
http://blogs.perl.org/users/preaction/2017/03/choosing-a-log-level.html
When to use the different log levels?
https://stackoverflow.com/questions/2031163/when-to-use-the-different-log-levels
I personally use this set of rule:
info|warn|error|fatal vs debug|trace
info|warn|error|fatal
debug|trace
info, warn and higher are to be shown to end users of application (non-developers) while debug and trace are meant only for developers. This means, debug and trace messages tend to be more technical and precise.
info
warn
debug
trace
info only for verbose output
info should only be shown when users specify increased verbosity, e.g. via command-line option --verbose.
--verbose
warn is for informing that there are some abnormality but not necessarily an error.
error
error is for error condition (obviously) but the program can continue.
fatal
fatal is for a serious error that renders the program unable to continue.
debug vs trace
Between debug and trace: 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 debug.
At the start of program, the level is set to warn. This means messages logged by log_info() or log_debug() by default won't be shown even after we set an output.
log_info()
log_debug()
To change level, you can use:
use Log::ger::Util; Log::ger::Util::set_level("info"); # or ... Log::ger::Util::set_level(40);
set_level() will die if you feed it an unknown level.
set_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 Perinci::CmdLine will already take care of this for you, so you don't need to do set_level manually at all.
set_level
Another module you can use for this purpose is Log::ger::Level::FromEnv. This module detects some environment variables (like LOG_LEVEL=debug, or TRACE=1) then set the logging level according to it.
LOG_LEVEL=debug
TRACE=1
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 %Log::ger::Levels, preferably before intializing logging for any package usign use Log::ger.
%Log::ger::Levels
use Log::ger
Some modules provide levels that mimic those in other frameworks, e.g. Log::ger::Level::Like::LogAny or other Log::ger::Level::Like::* modules.
Log::ger::Level::Like::*
perlancar <perlancar@cpan.org>
This software is copyright (c) 2019, 2018, 2017 by 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.
To install Log::ger::Manual, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Log::ger::Manual
CPAN shell
perl -MCPAN -e shell install Log::ger::Manual
For more information on module installation, please visit the detailed CPAN module installation guide.