1Log::Trivial(3) User Contributed Perl Documentation Log::Trivial(3)
2
6 Log::Trivial - Very simple tool for writing very simple log files
7
9 use Log::Trivial;
10 my $logger = Log::Trivial->new( log_file => 'path/to/my/file.log' );
11 $logger->set_level( 3 );
12 $logger->write(comment => 'foo' );
13
15 Use this module when you want use "Yet Another" very simple, light
16 weight log file writer.
17
19 new
20 The constructor can be called empty or with a number of optional
21 parameters.
22 $logger = Log::Trivial->new();
24 or
26 $logger = Log::Trivial->new(
28 log_file => '/my/config/file',
29 log_tag => $$,
30 no_date_tag => 1,
31 log_level => 2);
32 The log_tag is an optional string that is written to every log event
34 between the date at the comment, and is intended to help separate
35 logging events in environments when multiple applictions are
36 simultaneously writing to the same log file. For example you could pass
37 the PID of the applications, as shown in the example above. The
38 no_date_tag will supress the default date printing feature in the log
39 file.
40 set_log_file
42 The log file can be set after the constructor has been called. Simply
43 set the path to the file you want to use as the log file.
44 $logger->set_log_file( '/path/to/log.file' );
46 set_log_mode
48 Log::Trivial runs in two modes. The default mode is Multi mode: in this
49 mode the file will be opened and closed for each log file write. This
50 may be slower but allows multiple applications to write to the log file
51 at the same time. The alternative mode is called single mode: once you
52 start to write to the log no other application honouring flock will
53 write to the log. Single mode is potentially faster, and may be
54 appropriate if you know that only one copy of your application can
55 should be writing to the log at any given point in time.
56 WARNING: Not all system honour flock.
58 $logger->set_log_mode( 'multi' ); # Sets multi mode (the default)
60 or
62 $logger->set_log_mode( 'single' ); # Sets single mode
64 set_log_level
66 Log::Trivial uses very simple arbitrary logging level logic. Level 0 is
67 the highest priority log level, the lowest is the largest number
68 possible in Perl on your platform. You set the global log level for
69 your application using this function, and only log events of this level
70 or higher priority will be logged. The default level is 3.
71 $logger->set_log_level( 4 );
73 set_write_mode
75 Log::Trivial write log enteries using the POSIX synchronous mode by
76 default. This mode ensures that the data has actually been written to
77 the disk. This feature is not supported in all operating systems and
78 will slow down the disk write. By default this mode is enabled, in
79 future it may be disabled by default.
80 $logger->set_write_mode( 's' ); # sets synchronous (default)
82 $logger->set_write_mode( 'a' ); # sets asynchronous
83 set_no_date_tag
85 By default Log::Trivial will include the current time and date of each
86 individual log entry. You can turn this feature off with this method.
87 Time and date logging is on by default.
88 $logger->set_no_date_tag( 1 ); # Turns off date tagging
90 mark
92 If you just want to put a time stamp in the log stream this option will
93 send '-- MARK --' to the log. It probably only makes sense if you have
94 the time and date loggin option on.
95 $logger->mark( );
97 write
99 Write a log file entry.
100 $logger->write(
102 comment => 'My comment to be logged',
103 level => 3);
104 or
106 $logger->write( 'My comment to be logged' );
108 It will fail if the log file hasn't be defined, or isn't writable. It
110 will return the string written on success.
111 If you don't specify a log level, it will default to the current log
113 level and therefore log the event. Therefore if you always wish to log
114 something either specify a level of 0 or never specify a log level.
115 Log file entries are time stamped and have a newline carriage return
117 added automatically.
118 get_error
120 In normal operation the module should never die. All errors are non-
121 fatal. If an error occurs it will be stored internally within the
122 object and the method will return undef. The error can be read with the
123 get_error method. Only the most recent error is stored.
124 $logger->write( 'Log this' ) || say $logger->get_error( );
126
128 The log file format is very simple and fixed:
129 Time & date [tab] Your log comment [carriage return new line]
131 If you have enabled a log_tag then the log format will have an extra
133 element inserted in it.
134 Time & date [tab] log_tag [tab] Your log comment [carriage return new
136 line]
137 If you set the no_date_tag then the Time & date and the first tab will
139 be supressed.
140 DEPENDENCIES
142 At the moment the module only uses core modules. The test suite
143 optionally uses "Pod::Coverage", "Test::Pod::Coverage" and "Test::Pod",
144 which will be skipped if you don't have them.
145 History
147 See Changes file.
148
150 By default log write are POSIX synchronous, it is very unlikely that it
151 will run on any OS that does not support POSIX synchronous file
152 writing, this means it probably won't run on a VAX, Windows or other
153 antique system. It does run under Windows/Cygwin. To use non-POSIX
154 systems you need to turn off synchronous write.
155 Patches Welcome... ;-)
157 To Do
159 • Much better test suite.
160 • See if it's possible to work on non-POSIX like systems
162 automatically
163
165 None.
166
168 Adam Trickett, <atrickett@cpan.org>
169
171 perl, Log::Agent, Log::Log4perl, Log::Dispatch, Log::Simple
172
174 This version as "Log::Trivial", Copyright Adam John Trickett 2005-2014
175 OSI Certified Open Source Software. Free Software Foundation Free
177 Software.
178 This program is free software: you can redistribute it and/or modify it
180 under the terms of the GNU Lesser General Public License as published
181 by the Free Software Foundation, either version 3 of the License, or
182 (at your option) any later version.
183 This program is distributed in the hope that it will be useful, but
185 WITHOUT ANY WARRANTY; without even the implied warranty of
186 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
187 General Public License for more details.
188 You should have received a copy of the GNU Lesser General Public
190 License along with this program. If not, see
191 <http://www.gnu.org/licenses/>.
192perl v5.36.0 2023-01-20 Log::Trivial(3)