README
1$Id: README,v 1.1 2007/02/03 12:26:16 cmanley Exp $
2
3--------
4Abstract
5--------
6
7Log::Dispatch output class for logging to shared files.
8
9------------
10Requirements
11------------
12
13Log::Dispatch
14Params::Validate
15Time::HiRes
16Scalar::Util
17
18------------------
19Basic Installation
20------------------
21
22Log::Dispatch::FileShared may be installed through the CPAN shell
23in the usual manner:
24
25 # perl -MCPAN -e 'install Log::Dispatch::FileShared'
26
27You can also read this README from the CPAN shell:
28
29 # perl -MCPAN -e shell
30 cpan> readme Log::Dispatch::FileShared
31
32And you can install the component from the CPAN prompt as well:
33
34 cpan> install Log::Dispatch::FileShared
35
36-------------------
37Manual Installation
38-------------------
39
40Log::Dispatch::FileShared can also be installed manually. The latest CPAN
41version can be found at
42<http://www.cpan.org/modules/by-module/Log/> or in a
43similarly named directory at your favorite CPAN mirror.
44
45Downloading and unpacking the distribution are left as exercises for
46the reader. To build and test it:
47
48 perl Makefile.PL
49 make test
50
51When you're ready to install the component:
52
53 make install
54
55It should now be ready to use.
56
57On Win32 systems, replace "make" in the above commands with "nmake".
58The nmake utility can be downloaded from
59C<http://download.microsoft.com/download/vc15/Patch/1.52/W95/EN-US/Nmake15.exe>
60
61--------------------
62Module Documentation
63--------------------
64
65NAME
66 Log::Dispatch::FileShared - output class for logging to shared files.
67
68SYNOPSIS
69 use Log::Dispatch::FileShared;
70
71 my $output = Log::Dispatch::FileShared->new(
72 name => 'test',
73 min_level => 'info',
74 filename => 'application.log',
75 );
76
77 $output->log( level => 'emerg', message => 'Time to die.' );
78
79DESCRIPTION
80 This module provides an output class for logging to shared files under
81 the Log::Dispatch system.
82
83 Log messages are written using the flock file locking mechanism on a per
84 write basis which means that this module is suitable for sharing a log
85 file in a multitasking environment.
86
87 This class descends directly from Log::Dispatch::Output.
88
89OTHER SIMILAR CLASSES
90 Log::Dispatch::File doesn't provide any locking mechanism which makes it
91 unsuitable for sharing log files between multiple processes (unless you
92 don't mind having corrupt log messages on rare occasions).
93
94 Log::Dispatch::File::Locked does implement locking, but on a per open
95 handle basis which means that only a single process can log to the file
96 as long as the file is open. All other processes will block. The only
97 way to prevent other processes from blocking is to close the handle
98 after every write which degrades logging performance very much.
99 Therefore this class too is unsuitable for sharing log files between
100 multiple processes.
101
102METHODS
103 * new(%p)
104 This method takes a hash of parameters. The following options are
105 valid:
106
107 * name ($)
108 The name of the object (not the filename!). Required.
109
110 * min_level ($)
111 The minimum logging level this object will accept. See the
112 Log::Dispatch documentation on Log Levels for more
113 information. Required.
114
115 * max_level ($)
116 The maximum logging level this obejct will accept. See the
117 Log::Dispatch documentation on Log Levels for more
118 information. This is not required. By default the maximum is
119 the highest possible level (which means functionally that
120 the object has no maximum).
121
122 * filename ($)
123 The filename to be opened for appending.
124
125 * mode ($)
126 The mode the file should be opened with. Valid options are
127 '>' (write) and '>>' (append). The default is '>>' (append).
128
129 * perms ($)
130 If the file does not already exist, the permissions that it
131 should be created with. Optional. The argument passed must
132 be a valid octal value, such as 0600. It is affected by the
133 current or given umask.
134
135 * umask ($)
136 The optional umask to use when the file is created for the
137 first time.
138
139 * flock ($)
140 Whether or not log writes should be wrapped in a flock.
141 Defaults to true. If true, then for each logged message, a
142 non-blocking flock is attempted first, and if that fails,
143 then a blocking flock is attemped with a timeout.
144
145 * close_after_write ($)
146 Whether or not the file should be closed after each write.
147 This defaults to false. If set to true, then the mode will
148 aways be append, so that the file is not re-written for each
149 new message.
150
151 Note: opening and closing a file for each write is a
152 relatively slow process (especially on windoze systems) as
153 demonstrated in the performance benchmarks.
154
155 * close_after_modperl_request ($)
156 Only applicable for code running in a mod_perl (1 or 2)
157 environment and defaults to false. Set this to true if the
158 file should be closed after each mod_perl request which is
159 useful if you're using a persistent Log::Dispatch object and
160 intend to periodically roll your log files without having to
161 restart your web server each time.
162
163 * autoflush ($)
164 Whether or not the file should be autoflushed. This defaults
165 to true. If flock is true, then flushing always occurs no
166 matter what this is set to.
167
168 * callbacks( \& or [ \&, \&, ... ] )
169 This parameter may be a single subroutine reference or an
170 array reference of subroutine references. These callbacks
171 will be called in the order they are given and passed a hash
172 containing the following keys:
173
174 ( message => $log_message, level => $log_level )
175
176 The callbacks are expected to modify the message and then
177 return a single scalar containing that modified message.
178 These callbacks will be called when either the "log" or
179 "log_to" methods are called and will only be applied to a
180 given message once.
181
182 * log_message( message => $ )
183 Sends a message to the appropriate output. Generally this shouldn't
184 be called directly but should be called through the "log()" method
185 (in Log::Dispatch::Output).
186
187BENCHMARKS
188 FreeBSD 6.1 with a single Intel(R) Xeon(TM) CPU 3.60GHz
189 Measuring 10000 logs of using defaults...
190 Log::Dispatch::FileShared... 0.739 seconds (avg 0.00007)
191 Log::Dispatch::File... 0.622 seconds (avg 0.00006)
192 Measuring 10000 logs of using autoflush=0, flock=0...
193 Log::Dispatch::FileShared... 0.575 seconds (avg 0.00006)
194 Log::Dispatch::File... 0.574 seconds (avg 0.00006)
195 Measuring 10000 logs of using autoflush=1, flock=0...
196 Log::Dispatch::FileShared... 0.618 seconds (avg 0.00006)
197 Log::Dispatch::File... 0.623 seconds (avg 0.00006)
198 Measuring 10000 logs of using flock=1...
199 Log::Dispatch::FileShared... 0.739 seconds (avg 0.00007)
200
201 Measuring 10000 logs of using close_after_write=1, flock=0...
202 Log::Dispatch::FileShared... 1.080 seconds (avg 0.00011)
203 Log::Dispatch::File... 1.035 seconds (avg 0.00010)
204 Measuring 10000 logs of using close_after_modperl_request=1, flock=1...
205 Log::Dispatch::FileShared... 0.768 seconds (avg 0.00008)
206
207 MSWin32 with a Pentium CPU 3.0GHz
208 Measuring 10000 logs of using defaults...
209 Log::Dispatch::FileShared... 1.235 seconds (avg 0.00012)
210 Log::Dispatch::File... 1.047 seconds (avg 0.00010)
211 Measuring 10000 logs of using autoflush=0, flock=0...
212 Log::Dispatch::FileShared... 0.875 seconds (avg 0.00009)
213 Log::Dispatch::File... 0.907 seconds (avg 0.00009)
214 Measuring 10000 logs of using autoflush=1, flock=0...
215 Log::Dispatch::FileShared... 1.063 seconds (avg 0.00011)
216 Log::Dispatch::File... 1.047 seconds (avg 0.00010)
217 Measuring 10000 logs of using flock=1...
218 Log::Dispatch::FileShared... 1.251 seconds (avg 0.00013)
219
220 Measuring 10000 logs of using close_after_write=1, flock=0...
221 Log::Dispatch::FileShared... 74.128 seconds (avg 0.00741)
222 Log::Dispatch::File... 79.660 seconds (avg 0.00797)
223
224 Note how rediculously slow MSWin32 is when close_after_write=1 is
225 used.
226
227SEE ALSO
228 Log::Dispatch::File.
229
230AUTHOR
231 Craig Manley
232
233COPYRIGHT AND LICENSE
234 Copyright (C) 2007 Craig Manley This library is free software; you can
235 redistribute it and/or modify it under the same terms as Perl itself.
236