NAME
Log::Trivial - Very simple tool for writing very simple log files
SYNOPSIS
use Log::Trivial;
my $logger = Log::Trivial->new( log_file => 'path/to/my/file.log' );
$logger->set_level( 3 );
$logger->write(comment => 'foo' );DESCRIPTION
Use this module when you want use "Yet Another" very simple, light weight log file writer.
SUBROUTINES/METHODS
new
The constructor can be called empty or with a number of optional parameters.
$logger = Log::Trivial->new();or
$logger = Log::Trivial->new(
log_file => '/my/config/file',
log_tag => $$,
no_date_tag => 1,
log_level => 2);The log_tag is an optional string that is written to every log event between the date at the comment, and is intended to help separate logging events in environments when multiple applictions are simultaneously writing to the same log file. For example you could pass the PID of the applications, as shown in the example above. The no_date_tag will supress the default date printing feature in the log file.
set_log_file
The log file can be set after the constructor has been called. Simply set the path to the file you want to use as the log file.
$logger->set_log_file( '/path/to/log.file' );set_log_mode
Log::Trivial runs in two modes. The default mode is Multi mode: in this mode the file will be opened and closed for each log file write. This may be slower but allows multiple applications to write to the log file at the same time. The alternative mode is called single mode: once you start to write to the log no other application honouring flock will write to the log. Single mode is potentially faster, and may be appropriate if you know that only one copy of your application can should be writing to the log at any given point in time.
WARNING: Not all system honour flock.
$logger->set_log_mode( 'multi' ); # Sets multi mode (the default)or
$logger->set_log_mode( 'single' ); # Sets single modeset_log_level
Log::Trivial uses very simple arbitrary logging level logic. Level 0 is the highest priority log level, the lowest is the largest number possible in Perl on your platform. You set the global log level for your application using this function, and only log events of this level or higher priority will be logged. The default level is 3.
$logger->set_log_level( 4 );set_write_mode
Log::Trivial write log enteries using the POSIX synchronous mode by default. This mode ensures that the data has actually been written to the disk. This feature is not supported in all operating systems and will slow down the disk write. By default this mode is enabled, in future it may be disabled by default.
$logger->set_write_mode( 's' ); # sets synchronous (default)
$logger->set_write_mode( 'a' ); # sets asynchronousset_no_date_tag
By default Log::Trivial will include the current time and date of each individual log entry. You can turn this feature off with this method. Time and date logging is on by default.
$logger->set_no_date_tag( 1 ); # Turns off date taggingmark
If you just want to put a time stamp in the log stream this option will send '-- MARK --' to the log. It probably only makes sense if you have the time and date loggin option on.
$logger->mark( );write
Write a log file entry.
$logger->write(
comment => 'My comment to be logged',
level => 3);or
$logger->write( 'My comment to be logged' );It will fail if the log file hasn't be defined, or isn't writable. It will return the string written on success.
If you don't specify a log level, it will default to the current log level and therefore log the event. Therefore if you always wish to log something either specify a level of 0 or never specify a log level.
Log file entries are time stamped and have a newline carriage return added automatically.
get_error
In normal operation the module should never die. All errors are non-fatal. If an error occurs it will be stored internally within the object and the method will return undef. The error can be read with the get_error method. Only the most recent error is stored.
$logger->write( 'Log this' ) || say $logger->get_error( );LOG FORMAT
The log file format is very simple and fixed:
Time & date [tab] Your log comment [carriage return new line]
If you have enabled a log_tag then the log format will have an extra element inserted in it.
Time & date [tab] log_tag [tab] Your log comment [carriage return new line]
If you set the no_date_tag then the Time & date and the first tab will be supressed.
DEPENDENCIES
At the moment the module only uses core modules. The test suite optionally uses Pod::Coverage, Test::Pod::Coverage and Test::Pod, which will be skipped if you don't have them.
History
See Changes file.
BUGS AND LIMITATIONS
By default log write are POSIX synchronous, it is very unlikely that it will run on any OS that does not support POSIX synchronous file writing, this means it probably won't run on a VAX, Windows or other antique system. It does run under Windows/Cygwin. To use non-POSIX systems you need to turn off synchronous write.
Patches Welcome... ;-)
To Do
Much better test suite.
See if it's possible to work on non-POSIX like systems automatically
EXPORT
None.
AUTHOR
Adam Trickett, <atrickett@cpan.org>
SEE ALSO
perl, Log::Agent, Log::Log4perl, Log::Dispatch, Log::Simple
LICENSE AND COPYRIGHT
This version as Log::Trivial, Copyright Adam John Trickett 2005-2014
OSI Certified Open Source Software. Free Software Foundation Free Software.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.