Pitonyak::ADPLogger - Generate simple log messages to the screen and/or a log file.
The ADPLogger is wrtten such that it can be inherited.
Messages contain date and time information, a text string identifying the type, the line number from which the message was logged, and the text of the message itself.
YYYY.MM.DD hh:mm:ss <type>:<line> <message>
Supported message types include ERR, WARN, INFO, DEBUG, and TRACE.
use Pitonyak::ADPLogger;
my $log = new Pitonyak::ADPLogger();
# send debug output to the screen
$log->log_path('./logs/');
$log->log_name('TestLog');
$log->max_size(10000);
$log->max_logs(9);
# send debug output to the screen
$log->screen_output('DEBUG', 1);
$log->debug("Debug 1");
$log->warn("Hello I Warn you");
$log->debug(3, "Hello I debug you");
$log->info("Hello I info you");
$log->error("Hello I error you");
$log->configure(ConfigFileParser)
Configure the log object using a ConfigFileParser. A typical configuration section to configure a ADPLogger is:
log_name = FtpPoller # The extension .log is appended automatically
max_size = 100000 # Limit the size to 100,000 characters
max_logs = 9 # Allow 9 rolling logs
log_path = ./logs/ # Assuming a relative path can be dangerous
# Send everything to the screen except trace messages
log_screen_output_err = 1
log_screen_output_fatal; = 1
log_screen_output_warn = 1
log_screen_output_info = 1
log_screen_output_debug = 0
log_screen_output_trace = 0
# Send all messages except debug to the log file.
log_file_output_err = 1
log_file_output_fatal = 1
log_file_output_warn = 1
log_file_output_info = 1
log_file_output_debug = 0
log_file_output_trace = 0
Supported properties include:
Passes the value associated with 'log_path' to $log->log_path().
Passes the value associated with 'log_name' to $log->log_name().
Passes the configuration value associated with 'log_file_output_debug'
to $log->file_output('DEBUG', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_file_output_err'
to $log->file_output('ERR', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_file_output_fatal'
to $log->file_output('FATAL', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_file_output_info'
to $log->file_output('INFO', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_file_output_trace'
to $log->file_output('TRACE', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_file_output_warn'
to $log->file_output('WARN', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_screen_output_debug'
to $log->screen_output('DEBUG', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_screen_output_err'
to $log->screen_output('ERR', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_screen_output_fatal'
to $log->screen_output('FATAL', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_screen_output_info'
to $log->screen_output('INFO', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_screen_output_trace'
to $log->screen_output('TRACE', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the configuration value associated with 'log_screen_output_warn'
to $log->screen_output('WARN', $value).
The requested logging level, must be less than this value for a message
to be printed.
Passes the value associated with 'max_logs' to $log->max_logs().
Passes the value associated with 'max_size' to $log->max_size().
$log1->copy($log2)
Copy one ADPLogger into another
$log1->copy($log2) is the same as $log1 = $log2.
Open file handels are closed before the copy is performed, and the file handle itself is not copied.
Each message has a type. Supported message types include ERR, WARN, INFO, DEBUG, and TRACE.
ADPLogger::file_output()
Return the default hash of values used for logging output to a file.
$log->file_output()
Return the current hash of values used for logging output to a file.
For example:
$log->file_output('ERR') returns 1 if ERR output is logged to the file,
and 0 if it is not. This is the same as $log->file_output()->{'ERR'}.
$log->file_output(\%hash)
Use the hash reference to configure logging output to a file.
$log->file_output($message_type)
Returns the output value for the specified $message_type. For example:
$log->file_output('ERR') returns 1 if ERR output is logged to the file,
and 0 if it is not. This is the same as $log->file_output()->{'ERR'}.
Sets and then returns the output value for the specified $message_type.
For example:
$log->file_output('ERR', 1) causes ERR output to be logged to the file and
it returns the value 1 because the value was set to 1. The same can be accomplished
using $log->file_output()->{'ERR'} = 1.
The get_class_attribute method utilizes the fact that
$obj->method(@parms) is the same as
method($obj, @parms). This method does not perform type checking
to verify that this is true.
The get_class_attribute method is rarely called directly.
ADPLogger::get_class_attribute($attribute_name)
With only one paramter, the first parameter is assumed to be an attribute name and the default attribute value is returned.
$obj->get_class_attribute($attribute_name)
With two arguments, the first is assumed
to be a ADPLogger object and the second is
assumed to be an attribute name.
The attribute value for the object is returned.
$obj->get_class_attribute($attribute_value, $attribute_name)
With three arguments, the first is assumed to be the object, the second is a new attribute value, and the third is the attribute name to set. Although the order seems odd, this is intentional.
Consider the method is_ok defined as return get_class_attribute( @_, 'is_ok' );
Remember that @_ refers to the argument list passed to the method. In all cases, the last argument
passed to get_class_attribute is the attribute name. If the method is called directly,
this is the only argument.
$log->get_log_full_name()
Build and return the full path to the log file. Remember that $log->log_path()
returns a string with a trailing '/', so the value returned is equivalent to:
$log->is_ok()
Return 1 if the log file is considered OK, and 0 otherwise. If a value of 0 is returned, then no output will be sent to the file.
$log->is_ok(0|1)
Set the state of the log file to OK (1), or not OK (0). The value is usually not set externally, but rather, it is set automatically when the file is opened or closed.
All output methods accept a single string argument, which is written to the log file or the screen depending on the type and configuration. In all cases, a 1 is returned if the method is successful, and 0 otherwise.
$log->debug($message)
Write a message with log level one of type 'DEBUG' using write_log().
$log->debug($log_level, $message)
Write a message with the specified log level of type 'DEBUG' using write_log().
$log->error($message)
Write a message with log level one of type 'ERR' using write_log().
$log->error($log_level, $message)
Write a message with the specified log level of type 'ERR' using write_log().
$log->fatal($message)
Write a message with log level one of type 'FATAL' using write_log() and then die.
$log->fatal($log_level, $message)
Write a message with the specified log level of type 'FATAL' using write_log().
$log->info($message)
Write a message with log level one of type 'INFO' using write_log().
$log->info($log_level, $message)
Write a message with the specified log level of type 'INFO' using write_log().
$log->trace($message)
Write a message with log level one of type 'TRACE' using write_log().
$log->trace($log_level, $message)
Write a message with the specified log level of type 'TRACE' using write_log().
$log->warn($message)
Write a message with log level one of type 'WARN' using write_log().
$log->warn($log_level, $message)
Write a message with the specified log level of type 'WARN' using write_log().
Write a string directly to the log file and do not format the string in any way. One might argue that this is dangerous.
$log->write_string_to_log($to_screen, $to_file, $message)
Write the $message to the screen if $to_screen evaluates to true.
Write the $message to the file if $to_file evaluates to true.
Return 1 if successful, 0 otherwise.
The log_name is the base log name without the '.log' file extension. The full log name is built by concatinating log_path, log_name, and '.log';
log_name()
Return the default base log file name.
$log->log_name()
Return the base log file name for the log object.
$log->log_name(base_name)
Set the base log file name, used for the next log output. Do not include a file extension, because '.log' is automatically added.
The log_path identifies the directory containing the log file. The full log name is built by concatinating log_path, log_name, and '.log';
log_path()
Return the default path during initialization, which is './'.
$log->log_path()
Return the the path to the current log file.
$log->log_path(path)
Set the path for the log file, which will be used for the next log output. If the provided path does not contain '/' or '\', then '/' is appended to to the path. The path itself is not checked for validity.
If the provided path is an empty string, then the path is set to the default value.
When the maximum log file size is exceeded, filename.log is renamed to filename.log.1 before more text is written to filename.log. The max_logs argument sets the maximum number of "rolled" log files. So, setting this to 2 allows for filename.log.1 and filename.log.2.
$log->max_logs()
Return the maximum number of logs when the log files are rolled.
$log->max_logs(max number of rolled logs)
Set the maximum number of logs when the log files are rolled.
Maximum size for each log file. This value is checked before a new message is written to the file. If the file is too large, then the file is rolled into filename.log.1 and a new file is started.
$log->max_size()
Return the current maximum size.
$log->max_size(max desired log size)
Set the maximum file size.
$log2 = $log1->new()
Generate a new copy of a log object.
Each message has a type. Supported message types include ERR, WARN, INFO, DEBUG, and TRACE.
ADPLogger::screen_output()
Return the default hash of values used for logging output to a file.
$log->screen_output()
Return the current hash of values used for logging output to a file.
For example:
$log->screen_output('ERR') returns 1 if ERR output is logged to the file,
and 0 if it is not. This is the same as $log->screen_output()->{'ERR'}.
$log->screen_output(\%hash)
Use the hash reference to configure logging output to a file.
$log->screen_output($message_type)
Returns the output value for the specified $message_type. For example:
$log->screen_output('ERR') returns 1 if ERR output is logged to the file,
and 0 if it is not. This is the same as $log->screen_output()->{'ERR'}.
Sets and then returns the output value for the specified $message_type.
For example:
$log->screen_output('ERR', 1) causes ERR output to be logged to the file and
it returns the value 1 because the value was set to 1. The same can be accomplished
using $log->screen_output()->{'ERR'} = 1.
initialize()
The initialize() method is called automatically when an object is created.
The new method also calls initialize() directly
Initialize the data structure by copying values from the initial attributes hash into the newly created object. An IO File handle is created and added to the object if it does not already exist.
close_log()
Close the open file handle if the file handle exists and is open.
$log->is_log_open()
Returns non-zero if the log is open and zero if it is closed.
$log->open_log()
Open the logfile. returns non-zero on success and zero on failure.
If the log file is already open, as checked by $log->is_log_open(),
then the file is assumed to already be open.
$log->check_log_length()
check_log_length() is called before the log file is opened by
open_log().
If the current log file has size greater than max_size(),
then the log files are rolled.
$log->write_log($message_type, $log_level, $message)
The message type is immediately checked to see if the
message should be written to the file or the screen.
The message is logged if if the stated log_level is less or equal to
the configured log level.
If the message will not be written, then write_log()
immediately returns.
The line number of the calling function is obtained and the current date and time is determined. Finlly, the message text to write is created in the form:
YYYY.MM.DD hh:mm:ss <type>:<line> <message>
$log->write_string_to_log() is used to perform the actual write.
Returns 1 if successful, 0 otherwise
ADPLogger is taken from Pitonyak::SmallADPLogger, but significant funcationality has been removed.
First release of Pitonyak::SmallADPLogger.
Version 1.01 Changed internal documentation to POD
Version 1.02 Gutted the original code to create ADPLogger. The ADPLogger can use a Properties file for configuration, but there are also fewer options for configuration.