1Agent::Driver::File(3)User Contributed Perl DocumentationAgent::Driver::File(3)
2
3
4

NAME

6       Log::Agent::Driver::File - file logging driver for Log::Agent
7

SYNOPSIS

9        use Log::Agent;
10        require Log::Agent::Driver::File;
11
12        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

DESCRIPTION

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
35       The creation routine make() takes the following arguments:
36
37       "-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
43               -channels => {
44                   'error'   => '>&FILE',
45                   'output'  => '>newlog',   # recreate each time, don't append
46                   'debug'  => '|mailx -s whatever user',
47               }
48
49           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
53           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
60               my $rotate = Log::Agent::Rotate->make(
61                   -backlog     => 7,
62                   -unzipped    => 2,
63                   -max_write   => 100_000,
64                   -is_alone    => 1,
65               );
66
67               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
78           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
82       "-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
90       "-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
96           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
101           Default is false.
102
103       "-file" => file
104           This switch supersedes both "-duperr" and "-channels" by defining a
105           single file for all the channels.
106
107       "-perm" => perm
108           This switch supersedes "-chanperm" by defining consistent for all
109           the channels.
110
111       "-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
115           Default is false.
116
117       "-prefix" => prefix
118           The application prefix string to prepend to messages.
119
120       "-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
124           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
128       "-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
132           Default is false.
133
134       "-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
138               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
143           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

CHANNELS

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
152       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

CAVEAT

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
168       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
175        Rotation for 'logfile' may be wrong (shared with distinct policies)
176
177       emitted in the logs upon subsequent sharing.
178

AUTHORS

180       Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
181       currently maintained by Mark Rogaski <mrogaski@cpan.org>.
182
183       Thanks to Joseph Pepin for suggesting the file permissions arguments to
184       make().
185

LICENSE

187       Copyright (C) 1999 Raphael Manfredi.  Copyright (C) 2002 Mark Rogaski;
188       all rights reserved.
189
190       See Log::Agent(3) or the README file included with the distribution for
191       license information.
192

SEE ALSO

194       Log::Agent::Driver(3), Log::Agent(3), Log::Agent::Rotate(3).
195
196
197
198perl v5.38.0                      2023-07-20            Agent::Driver::File(3)
Impressum