/ 
Log-ger-Manual-0.040.000
River stage one • 1 direct dependent • 1 total dependent
/ Log::ger::Manual::Tutorial::300_Level

NAME

Log::ger::Manual::Tutorial::300_Level - Logging levels

VERSION

version 0.040.000

DESCRIPTION

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.

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 log_off or log_warning, only log_warn), but they are recognized e.g. when you feed one to 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:

I personally use this set of rules:

  • info|warn|error|fatal vs 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 only for verbose output

    info should only be shown when users specify increased verbosity, e.g. via command-line option --verbose.

  • warn

    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.

SETTING LEVEL

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.

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 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 Perinci::CmdLine takes care of this for you, so you don't need to do set_level manually at all.

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.

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 %Log::ger::Levels, preferably before intializing logging for any package using 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.

AUTHOR

perlancar <perlancar@cpan.org>

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.