1Agent::Driver::File(3)User Contributed Perl DocumentationAgent::Driver::File(3)
2
6 Log::Agent::Driver::File - file logging driver for Log::Agent
7
9 use Log::Agent;
10 require Log::Agent::Driver::File;
11 my $driver = Log::Agent::Driver::File->make(
13 -prefix => "prefix",
14 -duperr => 1,
15 -stampfmt => "own",
16 -showpid => 1,
17 -magic_open => 0,
18 -channels => {
19 error => '/tmp/output.err',
20 output => 'log.out',
21 debug => '../appli.debug',
22 },
23 -chanperm => {
24 error => 0777,
25 output => 0666,
26 debug => 0644
27 }
28 );
29 logconfig(-driver => $driver);
30
32 The file logging driver redirects logxxx() operations to specified
33 files, one per channel usually (but channels may go to the same file).
34 The creation routine make() takes the following arguments:
36 "-channels" => hash ref
38 Specifies where channels go. The supplied hash maps channel names
39 ("error", "output" and "debug") to filenames. When "-magic_open" is
40 set to true, filenames are allowed magic processing via perl's
41 open(), so this allows things like:
42 -channels => {
44 'error' => '>&FILE',
45 'output' => '>newlog', # recreate each time, don't append
46 'debug' => '|mailx -s whatever user',
47 }
48 If a channel (e.g. 'output') is not specified, it will go to the
50 'error' channel, and if that one is not specified either, it will
51 go to STDERR instead.
52 If you have installed the additional "Log::Agent::Rotate" module,
54 it is also possible to override any default rotating policy setup
55 via the "-rotate" argument: instead of supplying the channel as a
56 single string, use an array reference where the first item is the
57 channel file, and the second one is the "Log::Agent::Rotate"
58 configuration:
59 my $rotate = Log::Agent::Rotate->make(
61 -backlog => 7,
62 -unzipped => 2,
63 -max_write => 100_000,
64 -is_alone => 1,
65 );
66 my $driver = Log::Agent::Driver::File->make(
68 ...
69 -channels => {
70 'error' => ['errors', $rotate],
71 'output' => ['output, $rotate],
72 'debug' => ['>&FILE, $rotate], # WRONG
73 },
74 -magic_open => 1,
75 ...
76 );
77 In the above example, the rotation policy for the "debug" channel
79 will not be activated, since the channel is opened via a magic
80 method. See Log::Agent::Rotate for more details.
81 "-chanperm" => hash ref
83 Specifies the file permissions for the channels specified by
84 "-channels". The arguemtn is a hash ref, indexed by channel name,
85 with numeric values. This option is only necessary to override the
86 default permissions used by Log::Agent::Channel::File. It is
87 generally better to leave these permissive and rely on the user's
88 umask. See "umask" in perlfunc(3) for more details..
89 "-duperr" => flag
91 When true, all messages normally sent to the "error" channel are
92 also copied to the "output" channel with a prefixing made to
93 clearly mark them as such: "FATAL: " for logdie(), logcroak() and
94 logconfess(), "ERROR: " for logerr() and "WARNING: " for logwarn().
95 Note that the "duplicate" is the original error string for
97 logconfess() and logcroak(), and is not strictly identical to the
98 message that will be logged to the "error" channel. This is a an
99 accidental feature.
100 Default is false.
102 "-file" => file
104 This switch supersedes both "-duperr" and "-channels" by defining a
105 single file for all the channels.
106 "-perm" => perm
108 This switch supersedes "-chanperm" by defining consistent for all
109 the channels.
110 "-magic_open" => flag
112 When true, channel filenames beginning with '>' or '|' are opened
113 using Perl's open(). Otherwise, sysopen() is used, in append mode.
114 Default is false.
116 "-prefix" => prefix
118 The application prefix string to prepend to messages.
119 "-rotate" => object
121 This sets a default logfile rotation policy. You need to install
122 the additional "Log::Agent::Rotate" module to use this switch.
123 object is the "Log::Agent::Rotate" instance describing the default
125 policy for all the channels. Only files which are not opened via a
126 so-called magic open can be rotated.
127 "-showpid" => flag
129 If set to true, the PID of the process will be appended within
130 square brackets after the prefix, to all messages.
131 Default is false.
133 "-stampfmt" => (name | CODE)
135 Specifies the time stamp format to use. By default, my "own" format
136 is used. The following formats are available:
137 date "[Fri Oct 22 16:23:10 1999]"
139 none
140 own "99/10/22 16:23:10"
141 syslog "Oct 22 16:23:10".
142 You may also specify a CODE ref: that routine will be called every
144 time we need to compute a time stamp. It should not expect any
145 parameter, and should return a string.
146
148 All the channels go to the specified files. If a channel is not
149 configured, it is redirected to 'error', or STDERR if no 'error'
150 channel was configured either.
151 Two channels not opened via a magic open and whose logfile name is the
153 same are effectively shared, i.e. the same file descriptor is used for
154 both of them. If you supply distinct rotation policies (e.g. by having
155 a default policy, and supplying another policy to one of the channel
156 only), then the final rotation policy will depend on which one was
157 opened first. So don't do that.
158
160 Beware of chdir(). If your program uses chdir(), you should always
161 specify logfiles by using absolute paths, otherwise you run the risk of
162 having your relative paths become invalid: there is no anchoring done
163 at the time you specify them. This is especially true when configured
164 for rotation, since the logfiles are recreated as needed and you might
165 end up with many logfiles scattered throughout all the directories you
166 chdir()ed to.
167 Logging channels with the same pathname are shared, i.e. they are only
169 opened once by "Log::Agent::Driver::File". Therefore, if you specify
170 different rotation policy to such channels, the channel opening order
171 will determine which of the policies will be used for all such shared
172 channels. Such errors are flagged at runtime with the following
173 message:
174 Rotation for 'logfile' may be wrong (shared with distinct policies)
176 emitted in the logs upon subsequent sharing.
178
180 Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
181 currently maintained by Mark Rogaski <mrogaski@cpan.org>.
182 Thanks to Joseph Pepin for suggesting the file permissions arguments to
184 make().
185
187 Copyright (C) 1999 Raphael Manfredi. Copyright (C) 2002 Mark Rogaski;
188 all rights reserved.
189 See Log::Agent(3) or the README file included with the distribution for
191 license information.
192
194 Log::Agent::Driver(3), Log::Agent(3), Log::Agent::Rotate(3).
195perl v5.38.0 2023-07-20 Agent::Driver::File(3)