internal package Foswiki::Logger

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

• Foswiki::Logger::Compatibility - Compatibility with old LocalSite.cfg settings, if user has not run configure yet. This logger is automatically used if Foswiki senses that the LocalSite.cfg hasn't been modified for 1.1 (configure has not been run yet). It may also be explicitly selected in configure.
• Foswiki::Logger::PlainFile - Plain file implementation of the Foswiki Logger interface. Mostly compatible with TWiki (and Foswiki 1.0.0) log files, except that dates are recorded using ISO format, and include the time, and it dies when a log can't be written (rather than printing a warning).

internal package Foswiki::Logger

Object that interfaces to whatever records Foswiki log files.

This is a base class which will be subclassed by a class in the Logger subdirectory and selected by $Foswiki::cfg{Log}{Implementation}

Note that the implementation has to provide a way for the log to be replayed. Unfortunately this means that the simpler CPAN loggers are not suitable.

ObjectMethod finish()

Release memory. Subclasses must implement this if they use any fields in the object.

ObjectMethod log($level, @fields) or log( { param → 'value', } )

Adds a log message to a log.

Compatibility interface:

 $this->logger->log( 'info', $user, $action, $webTopic, $message, $remoteAddr );
 $this->logger->log( 'warning', $mess );
 $this->logger->log( 'debug', $mess );

Native interface:

 $this->logger->log( { level      => 'info',
                       user       => $user,
                       action     => $action,
                       webTopic   => $webTopic,
                       extra      => $message,
                       remoteAddr => $remoteAddr } );

 $this->logger->log( { level => 'warning',
                       caller => $caller,
                       fields  => \@fields } );

 $this->logger->log( { level => 'debug',
                       fields  => \@fields } );

Fields recorded for info messages are generally fixed. Any levels other than info can be called with an array of additional fields to log.

• $level - level of the event - one of debug, info, warning, error, critical, alert, emergency.
• @fields - an arbitrary list of fields to output to the log. These fields are recoverable when the log is enumerated using the eachEventSince method.

The levels are chosen to be compatible with Log::Dispatch.

StaticMethod eachEventSince($time, \@levels, $api) → $iterator

• $time - a time in the past
• \@levels - log levels to return events for.
• API version. If true, return hash name => value, otherwise return fixed list

Get an iterator over the list of all the events at the given level(s) between $time and now.

Events are returned in oldest-first order.

Each event is returned as a reference to an array. The first element of this array is always the date of the event (seconds since the epoch). Subsequent elements are the fields passed to log.

Note that a log implementation may choose to collapse several log levels into a single log. In this case, all messages in the same set as the requested level will be returned if any of the collapsed levels is selected.

ClassMethod setCommonFields( \%fhash )

• %fhash - Hashref of fields to be logged.

This routine assigns values to some common fields that are useful in logs.

In the older Logging API, these were only provided by the Foswiki::writeEvent() method for "info" level events.

$fhash→{agent}	The user agent
$fhash→{timestamp}	The time of the event
$fhash→{user}	The logged in user, if any
$fhash→{webTopic}	The current topic
$fhash→{remoteAddr}	Remote IP Address

ClassMethod getOldCall( \%fhash )

• %fhash - Hashref of fields to be logged.

This utility routine converts the new style hash calling convention into the older parameter list calling convention. Use it in an old logger to work with the new style calls in Foswiki 2.

In Foswiki 1.1 and earlier, event logs were "filtered" by the core. With Foswiki 2, the logger is responsible for filtering. This routine implements the 1.1 filter and returns undef if the record should not be logged.

    my $level;
    my @fields;

    # Native interface:  Convert the hash back to list format
    if ( ref( $_[0] ) eq 'HASH' ) {
        ($level, @fields) = Foswiki::Logger::getOldCall(@_);
        return unless defined $level;
    }
    else {
        ( $level, @fields ) = @_;
    }

Log4Perl compatibility methods

These methods implement the simple Log4Perl methods, for example =$this→logger→error('Some failure');

ObjectMethod debug( $message )

Equivalent to log( 'debug', $message )

ObjectMethod info( $message )

Equivalent to log( 'info', $message )

ObjectMethod notice( $message )

Equivalent to log( 'notice', $message )

ObjectMethod warn( $message )

Equivalent to log( 'warn', $message )

ObjectMethod error( $message )

Equivalent to log( 'error', $message )

ObjectMethod critical( $message )

Equivalent to log( 'critical', $message )

ObjectMethod alert( $message )

Equivalent to log( 'alert', $message )

ObjectMethod emergency( $message )

Equivalent to log( 'emergency', $message ).