1Log::Trivial(3)       User Contributed Perl Documentation      Log::Trivial(3)
2
3
4

NAME

6       Log::Trivial - Very simple tool for writing very simple log files
7

SYNOPSIS

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

DESCRIPTION

15       Use this module when you want use "Yet Another" very simple, light
16       weight log file writer.
17

SUBROUTINES/METHODS

19   new
20       The constructor can be called empty or with a number of optional
21       parameters.
22
23         $logger = Log::Trivial->new();
24
25       or
26
27         $logger = Log::Trivial->new(
28           log_file    => '/my/config/file',
29           log_tag     => $$,
30           no_date_tag => 1,
31           log_level   => 2);
32
33       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
41   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
45         $logger->set_log_file( '/path/to/log.file' );
46
47   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
57       WARNING: Not all system honour flock.
58
59         $logger->set_log_mode( 'multi' );    # Sets multi mode (the default)
60
61       or
62
63         $logger->set_log_mode( 'single' );    # Sets single mode
64
65   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
72         $logger->set_log_level( 4 );
73
74   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
81         $logger->set_write_mode( 's' );     # sets synchronous (default)
82         $logger->set_write_mode( 'a' );     # sets asynchronous
83
84   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
89         $logger->set_no_date_tag( 1 );   # Turns off date tagging
90
91   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
96         $logger->mark( );
97
98   write
99       Write a log file entry.
100
101         $logger->write(
102           comment => 'My comment to be logged',
103           level   => 3);
104
105       or
106
107         $logger->write( 'My comment to be logged' );
108
109       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
112       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
116       Log file entries are time stamped and have a newline carriage return
117       added automatically.
118
119   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
125         $logger->write( 'Log this' ) || say $logger->get_error( );
126

LOG FORMAT

128       The log file format is very simple and fixed:
129
130       Time & date [tab] Your log comment [carriage return new line]
131
132       If you have enabled a log_tag then the log format will have an extra
133       element inserted in it.
134
135       Time & date [tab] log_tag [tab] Your log comment [carriage return new
136       line]
137
138       If you set the no_date_tag then the Time & date and the first tab will
139       be supressed.
140
141   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
146   History
147       See Changes file.
148

BUGS AND LIMITATIONS

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
156       Patches Welcome... ;-)
157
158   To Do
159       •   Much better test suite.
160
161       •   See if it's possible to work on non-POSIX like systems
162           automatically
163

EXPORT

165       None.
166

AUTHOR

168       Adam Trickett, <atrickett@cpan.org>
169

SEE ALSO

171       perl, Log::Agent, Log::Log4perl, Log::Dispatch, Log::Simple
172
174       This version as "Log::Trivial", Copyright Adam John Trickett 2005-2014
175
176       OSI Certified Open Source Software.  Free Software Foundation Free
177       Software.
178
179       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
184       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
189       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/>.
192
193
194
195perl v5.36.0                      2023-01-20                   Log::Trivial(3)
Impressum