Log::Trivial(3pm)

📦
version 0.40 · 2 versions
, in fedora 43

💖 Log::Trivial 💖

okay bestie, so this is a page from the User Contributed Perl Documentation section — that's the 3pm part of Log::Trivial(3pm), iykyk — and it's about the sweetest, tiniest little logging module you ever did see. no cap.

✨ NAME ✨

Log::Trivial — the very simple tool for writing very simple log files. it's giving minimalism, it's giving no-fuss, it's giving "i just want a line in a file, please leave me alone." 💅

✨ SYNOPSIS ✨

use Log::Trivial;
my $logger = Log::Trivial->new( log_file => 'path/to/my/file.log' );
$logger->set_level( 3 );
$logger->write(comment => 'foo' );

look at that. three lines and you're logging. iconic behavior honestly. 🫶

✨ DESCRIPTION ✨

reach for this module when what you want is "Yet Another" very simple, light weight log file writer. that's the whole pitch. it's not trying to be Log4perl, it's trying to be a lil guy who writes lines. 🌸

✨ SUBROUTINES/METHODS ✨

🌈 new

the constructor. you can call it totally empty, or hand it a whole lil pile 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);

so, log_tag is an optional string that gets written into every single log event, and it lands between the date and the comment. the whole point of it is helping you tell logging events apart in environments where multiple applictions are all writing to the same log file at once. the classic move is passing the PID of the applications, exactly like that example up there does. and no_date_tag will supress the default date printing feature in the log file. (yes bestie, i said supress, that's how it's spelled in the source, don't @ me 😭)

🌈 set_log_file

you can set the log file after the constructor has already been called. just set the path to the file you want to use as the log file. easy.

$logger->set_log_file( '/path/to/log.file' );

🌈 set_log_mode

okay so Log::Trivial runs in two modes, and this is a real decision, not a vibe.

the default mode is Multi mode: in this mode the file gets opened and closed for each log file write. it may be slower, but it lets multiple applications write to the log file at the same time. slay, concurrency.

the alternative mode is called single mode: once you start writing to the log, no other application that honours flock will write to the log. single mode is potentially faster, and it may be appropriate if you know that only one copy of your application 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 mode

🌈 set_log_level

Log::Trivial uses very simple arbitrary logging level logic. Level 0 is the highest priority log level, and the lowest is the largest number possible in Perl on your platform. you set the global log level for your application with this function, and only log events of this level or higher priority will get logged. the default level is 3.

$logger->set_log_level( 4 );

🌈 set_write_mode

Log::Trivial writes log enteries using the POSIX synchronous mode by default. this mode ensures that the data has actually been written to the disk — like, actually actually. this feature is not supported in all operating systems and it will slow down the disk write. by default this mode is enabled, and in future it may be disabled by default. 👀

$logger->set_write_mode( 's' );     # sets synchronous (default)
$logger->set_write_mode( 'a' );     # sets asynchronous

🌈 set_no_date_tag

by default Log::Trivial will include the current time and date of each individual log entry. you can turn that feature off with this method. Time and date logging is on by default.

$logger->set_no_date_tag( 1 );   # Turns off date tagging

🌈 mark

if you just want to drop a time stamp into 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. the main character method, honestly. ✨

$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. on success it will return the string written. 🎀

if you don't specify a log level, it defaults to the current log level and therefore logs the event. so if you always want to log something, either specify a level of 0, or just never specify a log level at all. periodt.

log file entries are time stamped and have a newline carriage return added automatically. no manual newlines needed, bestie, it's handled.

🌈 get_error

in normal operation the module should never die. all errors are non-fatal. if an error occurs it gets 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 — it does not keep a whole history, so don't come crying to it about last week's oopsie.

$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. so no pressure. 🧚

🌸 History

See Changes file. that's it, that's the section. go read the changes file, babe.

✨ BUGS AND LIMITATIONS ✨

by default log write are POSIX synchronous, and it is very unlikely that it will run on any OS that does not support POSIX synchronous file writing. translation: it probably won't run on a VAX, Windows or other antique system. 💀

it does run under Windows/Cygwin though. and 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. nothing. zero. it exports nothing and it's proud of it. 👑

✨ AUTHOR ✨

Adam Trickett, <atrickett@cpan.org> 💜

✨ SEE ALSO ✨

perl, Log::Agent, Log::Log4perl, Log::Dispatch, Log::Simple — the whole friend group, if you ever need more than the lil guy. 🌈

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/>.

and that's the whole page bestie, no crumbs left 🍓 this one's running on perl v5.42.0, dated 2025-07-25, and it's still Log::Trivial(3pm) at heart. go write some extremely simple log files, you've got this 💖✨🎀

📦 where this page comes from