Badger::Log::File

NAME

Top Close Open

Badger::Log::File - writes log messages to a log file

SYNOPSIS

Top Close Open
use Badger::Log::File;

my $log = Badger::Log::File->new({
    filename  => '/var/log/badger.log',
    keep_open => 1,
});

$log->log('a debug message');
$log->info('an info message');
$log->warn('a warning message');
$log->error('an error message');
$log->fatal('a fatal error message');

DESCRIPTION

Top Close Open

This module is a subclass of Badger::Log that implements a simple mechanism for logging messages to a file. It uses Badger::Filesystem for all the underlying file operations.

CONFIGURATION OPTIONS

Top Close Open

The following configuration options are available in addition to those inherited form the Badger::Log base class.

filename

Top Close Open

The name of the log file which you want messages appended to. Either this or the filename_format option must be provided.

filename_format

Top Close Open

A format which can be used to generate a filename to write messages to. This can include any of the strftime() character sequences, e.g. %Y for the four digit year, %m for a two digit month number, %d for a two digit day of the month, etc.

my $log = Badger::Log::File->new({
    filename_format  => '/var/log/badger-%Y-%m-%d.log',
    keep_open => 1,
});

If, like me, you find it hard to remember the strftime() character sequences, then you can use an alternate format where the elements of the date and/or time are encoded as upper case words embedded in angle brackets. e.g. badger-<DATE>.log, or badger-<YEAR>-<MONTH>.log.

The words that can be embedded this way, and their corresponding strftime() character sequences are:

DATE    => '%Y-%m-%d'       # e.g. 2022-08-24
TIME    => '%H-%M-%S'       # e.g. 13:54:07
YEAR    => '%Y'             # e.g. 2022
MONTH   => '%m'             # e.g. 08
DAY     => '%d'             # e.g. 24
HOURS   => '%H'             # e.g. 13
MINUTES => '%M'             # e.g. 54
SECONDS => '%S'             # e.g. 07

The module will automatically create a new logfile when the filename_format generates a filename that is different to any previous value.

filesystem

Top Close Open

An optional reference to a Badger::Filesystem object, or the name of a filesystem class having a file() method similar to that in Badger::Filesystem. This defaults to the Badger::Filesystem class.

keep_open

Top Close Open

A flag indicating if the log file should be kept open between calls to logging methods. The default value is 0 meaning that the file will be opened for each message and closed again afterwards. Set it to any true value to have the file kept open.

METHODS

Top Close Open

The following methods are implemented in addition to those inherited from Badger::Log and its base classes.

log($level,$message)

Top Close Open

This method redefines the log() method in Badger::Log to write logging messages to the log file.

INTERNAL METHODS

Top Close Open

init(\%config)

Top Close Open

Custom initialiser method which calls the base class init_log() method followed by the init_file() method.

init_file(\%config)

Top Close Open

Custom initialiser method which handles the configuration and initialisation of the file-specific parts of the logger.

expand_filename()

Top Close Open

Expands the format defined by the filename_format configuration option to a filename using the current date and time.

If filename_format has not been specified then it returns the value of the filename configuration option.

filename_changed()

Top Close Open

Calls expand_filename() to expand any filename_format and compares it to the current filename (which may have been generated by a previous call to this method).

If they are the same then it returns undef. Otherwise it saves the new filename to the internal filename value and returns it.

file()

Top Close Open

Returns a reference to a Badger::Filesystem::File object based on the filename which can either be defined as a static configuration option or will be generated by the expand_filename() method from the filename_format configuration option.

filehandle()

Top Close Open

Returns a filehandle for the current logfile. If the filename has changed since the last call this method (determined by calling filename_changed()) then any existing filehandle is closed (by calling release()) and the new file is opened to return a new filehandle (by calling acquire()).

acquire()

Top Close Open

This method acquires a file handle (an IO::File object) for the specified filename, opened ready for appending log messages.

release()

Top Close Open

The method releases a previously acquired file handle. i.e. it closes the log file.

AUTHOR

Top Close Open

Andy Wardley http://wardley.org/

COPYRIGHT

Top Close Open

Copyright (C) 2005-2022 Andy Wardley. All Rights Reserved.

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

Fork Me on Github