NAME

Log::Contextual::WarnLogger - logger for libraries using Log::Contextual

VERSION

version 0.009001

SYNOPSIS

  package My::Package;
  use Log::Contextual::WarnLogger;
  use Log::Contextual qw( :log ),
    -default_logger => Log::Contextual::WarnLogger->new({
      env_prefix => 'MY_PACKAGE',
      levels => [ qw(debug info notice warning error critical alert emergency) ],
    });

  # warns '[info] program started' if $ENV{MY_PACKAGE_TRACE} is set
  log_info { 'program started' }; # no-op because info is not in levels
  sub foo {
    # warns '[debug] entered foo' if $ENV{MY_PACKAGE_DEBUG} is set
    log_debug { 'entered foo' };
    ...
  }

DESCRIPTION

This module is a simple logger made for libraries using Log::Contextual. We recommend the use of this logger as your default logger as it is simple and useful for most users, yet users can use "set_logger" in Log::Contextual to override your choice of logger in their own code thanks to the way Log::Contextual works.

METHODS

new

Arguments: Dict[ env_prefix => Str, levels => List ] $conf

  my $l = Log::Contextual::WarnLogger->new({ env_prefix => 'BAR' });

or:

  my $l = Log::Contextual::WarnLogger->new({
    env_prefix => 'BAR',
    levels => [ 'level1', 'level2' ],
  });

Creates a new logger object where env_prefix defines what the prefix is for the environment variables that will be checked for the log levels.

The log levels may be customized, but if not defined, these are used:

trace

debug

info

warn

error

fatal

For example, if env_prefix is set to FREWS_PACKAGE the following environment variables will be used:

  FREWS_PACKAGE_UPTO

  FREWS_PACKAGE_TRACE
  FREWS_PACKAGE_DEBUG
  FREWS_PACKAGE_INFO
  FREWS_PACKAGE_WARN
  FREWS_PACKAGE_ERROR
  FREWS_PACKAGE_FATAL

Note that UPTO is a convenience variable. If you set FOO_UPTO=TRACE it will enable all log levels. Similarly, if you set it to FATAL only fatal will be enabled.

$level

Arguments: @anything

All of the following six methods work the same. The basic pattern is:

  sub $level {
    my $self = shift;

    warn "[$level] " . join qq{\n}, @_;
      if $self->is_$level;
  }

trace

  $l->trace( 'entered method foo with args ' join q{,}, @args );

debug

  $l->debug( 'entered method foo' );

info

  $l->info( 'started process foo' );

warn

  $l->warn( 'possible misconfiguration at line 10' );

error

  $l->error( 'non-numeric user input!' );

fatal

  $l->fatal( '1 is never equal to 0!' );

If different levels are specified, appropriate functions named for your custom levels work as you expect.

Note: fatal does not call die for you, see "EXCEPTIONS AND ERROR HANDLING" in Log::Contextual

is_$level

All of the following six functions just return true if their respective environment variable is enabled.

is_trace

  say 'tracing' if $l->is_trace;

is_debug

  say 'debuging' if $l->is_debug;

is_info

  say q{info'ing} if $l->is_info;

is_warn

  say 'warning' if $l->is_warn;

is_error

  say 'erroring' if $l->is_error;

is_fatal

  say q{fatal'ing} if $l->is_fatal;

If different levels are specified, appropriate is_$level functions work as you would expect.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/haarg/Log-Contextual/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Arthur Axel "fREW" Schmidt.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Log::Contextual

perl -MCPAN -e shell
install Log::Contextual