Log::Monkey

• NAME
• SYNOPSIS
• DESCRIPTION
• SUBROUTINES
• STATE VARIABLES
• ENVIRONMENT
• LOG LINE HEADERS
• AUTHOR
• CODE
• CHANGELOG

NAME

Log::Monkey

SYNOPSIS

  BEGIN {
    $ENV{ LOGMONKEYLINEHEADERFORMAT } = $string;
    $ENV{ LOGMONKEYLOG }              = $string;
    $ENV{ LOGMONKEYPROGRAMNAME }      = $string;
    $ENV{ LOGMONKEYUSELINEHEADERS }   = $boolean;
    $ENV{ LOGMONKEYUSESTACKTRACES }   = $boolean;
  }

  use Log::Monkey;

Logging functions

  loggit( "Help!  I'm a prisoner in a log file!" );

  nloggit( "Help!\nI'm a prisoner\nin a log file!" );

  aloggit( "log info line 1", "log info line 2", "log info line 3" );
  aloggit( [ "log info line 1", "log info line 2", "log info line 3" ] );

  logger( "Log me to syslog!!" );

  barf( "Yikes!  Can't go on like this!" );
  pbarf( "\$some_parameter_name" );

State functions

  set_caller_level( $my_level );

  set_linehdr_format( $my_format );

  set_multiline_prefix( $my_prefix );

  set_program_name( $my_program_name );

  set_use_line_headers( 0 );

  set_use_stack_traces( 1 );

Utility functions

  $handle = loghandle();

  $line_header_string = linehdr();

  $stack_trace = stack_trace();

  $date_and_time         = timestamp( time => $seconds,
                                      what => "dt" );
  $current_date_and_time = timestamp();
  $date                  = timestamp( what => "d" );
  $time                  = timestamp( what => "t" );

DESCRIPTION

Log::Monkey provides routines to log information to an open file handle. There is a set of logging routines that do the actual logging, a set of state routines which modify various state values used by the package, and a set of utility routines which provide functionality to perform various tasks which prepare for logging and/or create logging meta-information.

SUBROUTINES

LOGGING FUNCTIONS

loggit()

  loggit( LIST );

loggit() appends its arguments as a single, newline-terminated string, to an open log handle and closes the handle.

loggit() joins its arguments into a single message string with the null string as the ``separator''. It deletes all newlines in the string and appends a single newline onto the end of the string. Then, it gets a log (file) handle, opened for appending. It uses a single print statement to append the message string to the log handle. If a problem was encountered in getting a log handle opened for appending, two things are logged to the system log:

• An indication that there was a problem opening the log handle

• The joined message string that was originally meant to be logged by loggit()

after which loggit() returns. Otherwise, after loggit() logs the message string and the log handle is closed if its file number is greater than 2.

nloggit()

  nloggit( LIST );

nloggit() logs similarly to loggit(), except that it splits the string made from its arguments on newlines and prints each field as a separate log line.

If the $multiline_prefix is set, its value is used as a prefix to each line logged. This prefix comes after any log line header, and before the actual data for the log line.

nloggit() sets $multiline_prefix to the null string before returning.

aloggit()

  aloggit( LIST );
  aloggit( ARRAYREF );

aloggit() logs similarly to loggit(), except that it logs each element of the input array as a separate log line. Like loggit() it deletes all newlines from its arguments and inserts a single newline at the end of each element of the array.

aloggit() uses and resets a multiline prefix in the same manner as nloggit() does.

logger()

  logger( LIST );

logger() logs its arguments to the system log via the system's logger(1) executable.

barf()

  barf( LIST );

barf() logs similarly to nloggit except that:

• barf() causes all processing to cease after logging by exiting with an error code, similar to die()

• Stack trace information is logged if $use_stack_traces is set.

• Each line is prefixed with the name of the caller

pbarf()

  pbarf( STRING );

``pbarf'' is pneumonic for ``parameter barf''. pbarf() expects its argument to be a string which names a parameter to a subroutine. Examples:

• ``\$foo''

• ``\@bar''

• ``\%bat''

pbarf() logs similarly to barf() except that the message that gets logged indicates that the parameter named was undefined. It is intended to be used to indicate that an expected subroutine parameter was undefined. Example:

  sub foo {
    my $baz = shift;
    not defined $baz and pbarf( "\$baz" );

    ...

  } # foo

which will cause something similiar to the following to be logged:

  main::foo(): $baz: undefined
      main::foo() called at some_perl_program line 17
      main::bar() called at some_perl_program line 13
      main::bat() called at some_perl_program line 10

STATE FUNCTIONS

set_caller_level()

  set_caller_level( POSITIVE_INTEGER );

set_caller_level() sets a state value which alters the stack trace output of barf() and pbarf(). Normally, the calls to barf() and pbarf() are omitted from the stack trace. This is when the package caller level variable has its default value of 1. If it is desired that the calls to barf() and pbarf() be shown in the stack traces, the level should be set to 0. If the caller wants to create their own function which calls barf() or pbarf(), say foobarf(), they might not want foobarf() to show up in the stack trace either. And if they create another function foobarf2(), which calls foobarf(), they might not want foobarf2() to show up in the stack trace. To get foobar() not to show, set the value to 2. To get foobar2() not to show, set it to 3. The general formula to make a function N levels above barf() and pbarf() in the stack trace is to set the caller level to N + 1.

For instance, the following code:

  set_use_stack_traces( $n );
  set_linehdr_format( "%P: " );

  set_caller_level( 0 );
  a();

  sub d { my $msg = shift; barf $msg }
  sub c { d( "Help!  The cpu's on fire!" ) }
  sub b { c() }
  sub a { b() }

will result in:

  $n == 0

    mypgm: Log::Monkey::barf(): Help!  The cpu's on fire!
    mypgm: Log::Monkey::barf():     Log::Monkey::barf('Help!  The cpu\'s on fire!') called at ./mypgm.perl line 14
    mypgm: Log::Monkey::barf():     main::d('Help!  The cpu\'s on fire!') called at ./mypgm.perl line 15
    mypgm:     main::c() called at ./mypgm.perl line 16
    mypgm:     main::b() called at ./mypgm.perl line 17
    mypgm:     main::a() called at ./mypgm.perl line 12

  $n == 1

    mypgm: main::d(): Help!  The cpu's on fire!
    mypgm: main::d():     main::d('Help!  The cpu\'s on fire!') called at ./mypgm.perl line 15
    mypgm:     main::c() called at ./mypgm.perl line 16
    mypgm:     main::b() called at ./mypgm.perl line 17
    mypgm:     main::a() called at ./mypgm.perl line 12

  $n == 2

    mypgm: main::c(): Help!  The cpu's on fire!
    mypgm:     main::c() called at ./mypgm.perl line 18
    mypgm:     main::b() called at ./mypgm.perl line 19
    mypgm:     main::a() called at ./mypgm.perl line 14

  $n == 3

    mypgm: main::b(): Help!  The cpu's on fire!
    mypgm:     main::b() called at ./mypgm.perl line 19
    mypgm:     main::a() called at ./mypgm.perl line 14

  $n == 4

    mypgm: main::a(): Help!  The cpu's on fire!
    mypgm:     main::a() called at ./mypgm.perl line 14

  set_linehdr_format( STRING );

  set_multiline_prefix( STRING );

  set_program_name( STRING );

  set_use_line_headers( STRING );

  set_use_stack_traces( STRING );

  HANDLE = loghandle();

  /^\s*stderr\s*$/i

  $line_header_string = linehdr();

  $stack_trace_string = stack_trace();

  timestamp( time => $integer,
             what => $string );

  timestamp( time => $integer );

  timestamp( what => $string  );

  timestamp();

  YYYY-mm-dd

  HH:MM:SS

  YYYY-mm-dd HH:MM:SS

STATE VARIABLES

Each of these (unexported) variables has an associated subroutine to change its value (which the caller is expected to use).

$linehdr_format

The value of $linehdr_format is interpreted to be format specifier for log line headers. Its initial value is given by $ENV{ LOGMONKEYLINEHEADERFORMAT } if it exists and is defined. Otherwise it is initially given a default value of ``%d %t %P[%p]: ''. At any time, the set_linehdr_format() subroutine may be called to change its value. Please see set_linehdr_format() for a discussion of how this format specifier is interpreted.

$multiline_prefix

The value of $multiline_prefix is interpreted to be a string which will be inserted in logged lines between a log line header, if present, and the information to be logged. It is used by aloggit() and nloggit() to logically associate multiple log lines with each other. For example, if the value of $multiline_prefix were ``level 4: '', then the following:

  nloggit( "The quick\nbrown\nfox jumps over the\nlazy dog." );

would result in these lines being logged:

  2003-02-05 17:03:39 myhost mypgm[14293]: level 4: The quick
  2003-02-05 17:03:39 myhost mypgm[14293]: level 4: brown
  2003-02-05 17:03:39 myhost mypgm[14293]: level 4: fox jumps over the
  2003-02-05 17:03:39 myhost mypgm[14293]: level 4: lazy dog.

(assuming $linehdr_format contained the default value).

The initial value for $multiline_prefix is the null string. There is no environment variable from which $multiline_prefix may get is initial value. The value of $multiline_prefix may be set at any time using the set_multiline_prefix() subroutine.

Note that each call to aloggit() or nloggit() resets the value of this variable to the null string.

$program_dollar_zero

The value of $program_dollar_zero is initially set from $ENV{ LOGMONKEYPROGRAMNAME } if it is defined. If this environment variable is not set, $program_dollar_zero gets a default value of $0. $program_dollar_zero is expected to be the fully qualified path name to the program using this package. This path name is used in log line headers if included in the line header format string.

The value of $program_dollar_zero may be changed at any time using the set_program_name() subroutine.

$program_basename

The value of $program_basename is initially set after $program_dollar_zero is set and is the basename of $program_dollar_zero. Whenever $program_dollar_zero is changed in set_program_name(), $program_basename is updated to reflect the change.

$use_line_headers

The value of $use_line_headers is used to indicate whether log line headers are used. If $use_line_headers evaluates to true, line headers are used. $use_line_headers takes its initial value from $ENV{ LOGMONKEYUSELINEHEADERS } if defined. If not, it is set to a default value of 1. Its value can be changed at any time by calling set_use_line_headers().

$use_stack_traces

The value of $use_stack_traces is used to indicate whether stack trace information is logged. If $use_stack_traces evaluates to true, stack trace information is logged. $use_stack_traces takes its initial value from $ENV{ LOGMONKEYUSESTACKTRACES } if defined. If not, it is set to a default value of 0. Its value can be changed at any time by calling set_use_stack_traces().

ENVIRONMENT

$ENV{ LOGMONKEYLINEHEADERFORMAT }

If this variable is set at package initialization, it will be used as the value of the line header format string. Please see set_linehdr_format() for more details.

$ENV{ LOGMONKEYLOG }

This variable is used to determine to where logging should be done. If it is undefined, false, or matches ``stderr'' in upper, lower, or any kind of mixed case, then STDERR is used for logging. Else the value of the variable is taken to be the path to the log file which should be used.

$ENV{ LOGMONKEYPROGRAMNAME }

If this variable is set at package initialization, it will be used as the fully qualified path to the calling program in log line headers.

$ENV{ LOGMONKEYUSELINEHEADERS }

If this variable is set at package initialization, it will be used to indicate whether line headers will be used. Log line headers will be suppress if and only if the variable is defined and evaluates to true.

$ENV{ LOGMONKEYUSESTACKTRACES }

If this variable is set at package initialization, it will be used to indicate whether stack trace information should be logged by those subroutines that are able to do so. If this variable is defined and its value evaluates to true, then stack trace information will be logged.

Here is an example of output that includes a stack trace:

    main::foo(): Sheesh!  Gimme a stack trace!
        main::foo() called at some_perl_program line 17
        main::bar() called at some_perl_program line 13
        main::bat() called at some_perl_program line 10

LOG LINE HEADERS

Let's use the following call as an example:

  loggit( "Look, Ma!  No hands!" );

If the use of log line headers is not suppressed (it is not by default), what gets logged is something like:

  2002-05-15 09:50:28 myhost myprogram[14498]: Look, Ma!  No hands!

If the use of log line headers is suppressed, what gets logged is simply:

  Look, Ma!  No hands!

loggit(), aloggit(), and nloggit() use log line headers (unless they are suppressed).

AUTHOR

David Alban <extasia@extasia.org>