NAME

Log::ger::App - An easy way to use Log::ger in applications

VERSION

version 0.025

SYNOPSIS

In your script:

use Log::ger::App;
use Your::App::Module; # your module which uses Log::ger to do its logging

If you also do logging in your script:

use Log::ger::App;
use Log::ger;

log_warn("Some log ...");

DESCRIPTION

This module basically loads Log::ger::Output::Composite with some sensible defaults and allows customizing some aspects via environment variable.

Default outputs

Code                            Screen  File                   Syslog
------------------------------  ------  ----                   ------
One-liner (-e)                  y       -                      -
Script running as normal user   y       ~/PROGNAME.log         -
Script running as root          y       /var/log/PROGNAME.log  -
Daemon                          -       /var/log/PROGNAME.log  y

Determining if script is a daemon

Log::ger::App assumes your script is a daemon if some daemon-related modules are loaded, e.g. App::Daemon, HTTP::Daemon, Net::Daemon, etc (see the source code for the complete list). Alternatively, you can also set $main::IS_DAEMON to 1 (0) to specifically state that your script is (not) a daemon. Or, you can set it via import argument (see "import").

Setting general log level

Via import argument 'level'. You can set general log level via import argument level (see "import") but users of your script will not be able to customize it:

use Log::ger::App level => 'debug'; # hard-coded to debug, not recommended

Via environment variables. You can also set general log level from environment using LOG_LEVEL (e.g. LOG_LEVEL=trace to set level to trace or LOG_LEVEL=0 to turn off logging). Alternatively, you can set to trace using TRACE=1, or debug with DEBUG=1, info with VERBOSE=1, error with QUIET=1.

Via import argument 'default_level'. If the environment variables does not provide a value, next the import argument default_level is consulted. This is the preferred method of setting default level:

use Log::ger::App default_level => 'info'; # be verbose by default. unless changed by env vars

Via main package variable $main::Default_Log_Level. The next value to be consulted is the main package variable $main::Default_Log_Level. The name of the variable can be customized using the import argument default_level_var_name. Note that you need to set the variable's value before loading Log::ger::App, so this does not work:

use Log::ger::App;
our $Default_Log_Level = 'info';

this does not also:

our $Default_Log_Level = 'info';
use Log::ger::App;

but this does:

BEGIN { our $Default_Log_Level = 'info' }
use Log::ger::App;

Fallback value "warn". The fallback level is warn, if all the above does not provide a value.

Setting per-output log level

Via environment variables. You can set level for each output using OUTPUT_NAME_{LOG_LEVEL|TRACE|DEBUG|VERBOSE|QUIET} environment variables. For example, SCREEN_DEBUG=1 to set screen level to debug or FILE_LOG_LEVEL=off to turn off file logging.

General level. If the environment variables do not provide a value, the general level (see "Setting general log level") will be used.

Showing timestamp

Timestamps are shown in log files. On the screen, timestamps are not shown by default. To show timestamps on the screen, set LOG_ADD_TIMESTAMP to true. For example, when timestamps are not shown:

myprog: First log message
myprog: Doing task 1 ...
myprog: Doing task 2 ...

When timestamps are shown:

myprog: [2018-08-30T15:14:50] First log message
myprog: [2018-08-30T15:14:50] Doing task 1 ...
myprog: [2018-08-30T15:15:01] Doing task 2 ...

FUNCTIONS

import

Usage:

$pkg->import(%args)

Arguments:

level

str|num. Explicitly set a hard-coded level. Not recommended because of lack of flexibility. See instead: "default_level".
default_level

str|num. Instead of hard-coding level with "level", you can set a default level. Environment variables will be consulted first (as described in "DESCRIPTION") before falling back to this level.
default_level_var_name

str. Optional. Name of scalar variable (without the sigil) to be consulted for the default level (after the default_level import argument). If the name of the variable does not contain package name, it will be assumed to be in the "main" package. The default value is main::Default_Log_Level.
name

str. Explicitly set program name. Otherwise, default will be taken from $0 (after path and '.pl' suffix is removed) or set to prog.

Program name will be shown on the screen, e.g.:
```
myprog: First log message
myprog: Doing task 1 ...
myprog: Doing task 2 ...
myprog: Exiting ...
```
file_name

str. Explicitly set log filename. By default, filename will be set to name.log.
file_dir

str. Explicitly set log file's directory. By default, it is user's home (if not running as root), or /var/log (if running as root).
daemon

bool. Explicitly tell Log::ger::App that your application is a daemon or not. Otherwise, Log::ger::App will try some heuristics to guess whether your application is a daemon: from the value of $main::IS_DAEMON and from the presence of modules like HTTP::Daemon, Proc::Daemon, etc.

outputs

hash. Specify extra outputs. Will be added to Log::ger::Output::Composite's outputs configuration.

Example:

outputs => {
    DirWriteRotate => {
        conf => {dir=>'/home/ujang/log', max_size=>10_000},
        level => 'off',
        category_level => {Dump => 'info'},
    },
},

extra_conf

Hash. Specify extra configuration, will be added to Log::ger::Output::Composite's configuration.

Example:
```
extra_conf => {
    category_level => {Dump => 'off'},
},
```

VARIABLES

$DEBUG

Default is false. If set to true, will show more details about how log level, etc is set.

@IMPORT_ARGS

Will be set with the last aguments passed to import(), for informational purposes.

ENVIRONMENT

LOG_GER_APP_DEBUG

Used to set the default for $DEBUG.

LOG_ADD_LOCATION

Boolean. Default to false. If set to true, will add location to the log:

[file /some/path.pm:123]

LOG_ADD_STACK_TRACE

Boolean. Default to false. If set to true, will add stack trace to the log:

[stack ...]

LOG_ADD_TIMESTAMP

Boolean. Default to false. If set to true, will add timestamps to the screen log. Normally, timestamps will only be added to the file log.

LOG_ADD_MEMORY_INFO

Boolean. Default to false. If set to true, will add memory info to log (see %_{vmtime} pattern in Log::ger::Layout::Pattern).

LOG_LEVEL

String. Can be set to off or numeric/string log level.

TRACE

Bool.

DEBUG

Bool.

VERBOSE

Bool.

QUIET

Bool.

SCREEN_LOG_LEVEL

SCREEN_TRACE

SCREEN_DEBUG

SCREEN_VERBOSE

SCREEN_QUIET

FILE_LOG_LEVEL

FILE_TRACE

FILE_DEBUG

FILE_VERBOSE

FILE_QUIET

SYSLOG_LOG_LEVEL

SYSLOG_TRACE

SYSLOG_DEBUG

SYSLOG_VERBOSE

SYSLOG_QUIET

FAQS

How do I turn off file logging?

By default, file logging is on unless running as a Perl one-liner (under perl's -e).

To explicitly turn file logging off, you can set FILE_LEVEL environment variable to off, for example:

BEGIN { $ENV{FILE_LEVEL} //= "off" }
use Log::ger::App;

How do I turn off screen logging?

By default, screen logging is on unless script is a daemon.

To explicitly turn screen logging off, you can set SCREEN_LEVEL environment variable to off, for example:

BEGIN { $ENV{SCREEN_LEVEL} //= "off" }
use Log::ger::App;

How do I turn off syslog logging?

By default, syslog logging is on if script is a daemon.

To explicitly turn syslog logging off, you can set SYSLOG_LEVEL environment variable to off, for example:

BEGIN { $ENV{SYSLOG_LEVEL} //= "off" }
use Log::ger::App;

Why doesn't setting $main::Default_Log_Level work?

Note that you need to set the variable's value before loading Log::ger::App, so this does not work:

use Log::ger::App;
our $Default_Log_Level = 'info';

this does not also:

our $Default_Log_Level = 'info';
use Log::ger::App;

but this does:

BEGIN { our $Default_Log_Level = 'info' }
use Log::ger::App;

Why doesn't re-setting log level using Log::ger::Util::set_level() work?

(This FAQ item is from Log::ger::Output::Composite's, slightly modified).

The Log::ger::Output::Composite plugin that Log::ger::App uses sets its own levels and logs using a multilevel routine (which gets called for all levels). Re-setting log level dynamically via Log::ger::Util's set_level will not work as intended, which is fortunate or unfortunate depending on your need.

If you want to override all levels settings with a single value, you can use Log::ger::Output::Composite::set_level, for example:

Log::ger::Util::set_level('trace'); # also set this too
Log::ger::Output::Composite::set_level('trace');

This sets an internal level setting which is respected and has the highest precedence so all levels settings will use this instead. If previously you have:

Log::ger::Output->set(Composite => (
    outputs => {
        File   => {conf=>{path=>'/foo'}, level=>'debug'},
        Screen => {level=>'info', category_level=>{MyApp=>'warn'}},
    },
    category_level => {
        'MyApp::SubModule1' => 'debug',
    },
));

then after the Log::ger::Output::Composite::set_level('trace'), all the above per-category and per-output levels will be set to trace.

AUTHOR

perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE

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::App, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Log::ger::App

CPAN shell

perl -MCPAN -e shell
install Log::ger::App

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

Default outputs

Determining if script is a daemon

Setting general log level

Setting per-output log level

Showing timestamp

FUNCTIONS

import

VARIABLES

$DEBUG

@IMPORT_ARGS

ENVIRONMENT

LOG_GER_APP_DEBUG

LOG_ADD_LOCATION

LOG_ADD_STACK_TRACE

LOG_ADD_TIMESTAMP

LOG_ADD_MEMORY_INFO

LOG_LEVEL

TRACE

DEBUG

VERBOSE

QUIET

SCREEN_LOG_LEVEL

SCREEN_TRACE

SCREEN_DEBUG

SCREEN_VERBOSE

SCREEN_QUIET

FILE_LOG_LEVEL

FILE_TRACE

FILE_DEBUG

FILE_VERBOSE

FILE_QUIET

SYSLOG_LOG_LEVEL

SYSLOG_TRACE

SYSLOG_DEBUG

SYSLOG_VERBOSE

SYSLOG_QUIET

FAQS

How do I turn off file logging?

How do I turn off screen logging?

How do I turn off syslog logging?

Why doesn't setting $main::Default_Log_Level work?

Why doesn't re-setting log level using Log::ger::Util::set_level() work?

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions