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

VERSION
    version 0.023

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 => {
         default_level => 'error',
         outputs => {
             File => {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".

SEE ALSO
    Log::ger

AUTHOR
    perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2022, 2021, 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.

