NAME

Data::AnyXfer::Log4perl - Unified logging system

SYNOPSIS

  use Data::AnyXfer::Log4perl;    # exports 'get_logger'

  my $logger = get_logger();
  $logger->debug( 'Eeep! Someone pressed the 'wings fall off' button!' );

DESCRIPTION

This module provides an easy and centralized way to do logging, which will probably be most useful during development and when trying to track down issues in code.

SWITCHING ON LOGGING

By default all logging is suppressed, which is probably what you want during production. However there are several ways to switch on the logging:

When this module is first used it looks for a config file to read in. It tries the following in order:

  $ENV{HHOLDINGS_LOGGING_CONFIG_FILE}
  '~/hholdings_logging.conf'
  '/etc/hholdings_logging.conf'

The first one to be found is used and the search stops. The contents are as described in Log::Log4perl::Config. If no file is found then a default config is used which suppresses all output - as if the logging didn't exist.

If you are on a dev box and want to enable logging for all the *.pm files in your working dir then you can use the DATA_ANYXFER_LOG_LEVEL environment variable to switch on logging:

  DATA_ANYXFER_LOG_LEVEL=INFO perl t/your_test.t

If you want to set the logging config from a file in the code remember to use a BEGIN block so that the $ENV is set before this module is compiled.

CONFIG FILE FORMAT

For full details see Log::Log4perl::Config and Log::Log4perl::Layout::PatternLayout. Below is a sample config that will be a good place to start:

  # Switch everything off by default
  log4perl.logger = OFF, Screen

  # log everything of DEBUG and above in Buggy
  log4perl.logger.Buggy = DEBUG, Screen

  # Set up simple logging to the screen (with coloured output)
  log4perl.appender.Screen = Log::Log4perl::Appender::ScreenColoredLevels
  log4perl.appender.Screen.layout = Log::Log4perl::Layout::PatternLayout
  log4perl.appender.Screen.layout.ConversionPattern = %p %rms %C %m%n

  # Set up the file logging
  log4perl.appender.A1 = Log::Log4perl::Appender::File
  log4perl.appender.A1.filename = /tmp/hholdings.log
  log4perl.appender.A1.mode = append
  log4perl.appender.A1.layout = Log::Log4perl::Layout::PatternLayout
  log4perl.appender.A1.layout.ConversionPattern = %p %d %C %m%n

  # Suppress unwanted duplicate messages
  log4perl.oneMessagePerAppender = 1

METHODS

get_logger => $logger = get_logger();

Returns a correctly configured Log::Log4perl object using a config found as described above. Always exported.

COPYRIGHT

This software is copyright (c) 2019, Anthony Lucas.

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