 |
|
| |
Agent::Driver::File(3) |
User Contributed Perl Documentation |
Agent::Driver::File(3) |
Log::Agent::Driver::File - file logging driver for Log::Agent
use Log::Agent;
require Log::Agent::Driver::File;
my $driver = Log::Agent::Driver::File->make(
-prefix => "prefix",
-duperr => 1,
-stampfmt => "own",
-showpid => 1,
-magic_open => 0,
-channels => {
error => '/tmp/output.err',
output => 'log.out',
debug => '../appli.debug',
},
-chanperm => {
error => 0777,
output => 0666,
debug => 0644
}
);
logconfig(-driver => $driver);
The file logging driver redirects logxxx() operations to specified files,
one per channel usually (but channels may go to the same file).
The creation routine make() takes the following
arguments:
- "-channels" => hash ref
- Specifies where channels go. The supplied hash maps channel names
("error",
"output" and
"debug") to filenames. When
"-magic_open" is set to true, filenames
are allowed magic processing via perl's open(), so this allows
things like:
-channels => {
'error' => '>&FILE',
'output' => '>newlog', # recreate each time, don't append
'debug' => '|mailx -s whatever user',
}
If a channel (e.g. 'output') is not specified, it will go to
the 'error' channel, and if that one is not specified either, it will go
to STDERR instead.
If you have installed the additional
"Log::Agent::Rotate" module, it is
also possible to override any default rotating policy setup via the
"-rotate" argument: instead of
supplying the channel as a single string, use an array reference where
the first item is the channel file, and the second one is the
"Log::Agent::Rotate"
configuration:
my $rotate = Log::Agent::Rotate->make(
-backlog => 7,
-unzipped => 2,
-max_write => 100_000,
-is_alone => 1,
);
my $driver = Log::Agent::Driver::File->make(
...
-channels => {
'error' => ['errors', $rotate],
'output' => ['output, $rotate],
'debug' => ['>&FILE, $rotate], # WRONG
},
-magic_open => 1,
...
);
In the above example, the rotation policy for the
"debug" channel will not be activated,
since the channel is opened via a magic method. See
Log::Agent::Rotate for more details.
- "-chanperm" => hash ref
- Specifies the file permissions for the channels specified by
"-channels". The arguemtn is a hash ref,
indexed by channel name, with numeric values. This option is only
necessary to override the default permissions used by
Log::Agent::Channel::File. It is generally better to leave these
permissive and rely on the user's umask. See "umask" in
perlfunc(3) for more details..
- "-duperr" => flag
- When true, all messages normally sent to the
"error" channel are also copied to the
"output" channel with a prefixing made
to clearly mark them as such: "FATAL: " for logdie(),
logcroak() and logconfess(), "ERROR: " for
logerr() and "WARNING: " for logwarn().
Note that the "duplicate" is the original error
string for logconfess() and logcroak(), and is not
strictly identical to the message that will be logged to the
"error" channel. This is a an
accidental feature.
Default is false.
- "-file" => file
- This switch supersedes both "-duperr"
and "-channels" by defining a single
file for all the channels.
- "-perm" => perm
- This switch supersedes "-chanperm" by
defining consistent for all the channels.
- "-magic_open" => flag
- When true, channel filenames beginning with '>' or '|' are opened using
Perl's open(). Otherwise, sysopen() is used, in append mode.
Default is false.
- "-prefix" => prefix
- The application prefix string to prepend to messages.
- "-rotate" => object
- This sets a default logfile rotation policy. You need to install the
additional "Log::Agent::Rotate" module
to use this switch.
object is the
"Log::Agent::Rotate" instance
describing the default policy for all the channels. Only files which are
not opened via a so-called magic open can be rotated.
- "-showpid" => flag
- If set to true, the PID of the process will be appended within square
brackets after the prefix, to all messages.
Default is false.
- "-stampfmt" => (name | CODE)
- Specifies the time stamp format to use. By default, my "own"
format is used. The following formats are available:
date "[Fri Oct 22 16:23:10 1999]"
none
own "99/10/22 16:23:10"
syslog "Oct 22 16:23:10".
You may also specify a CODE ref: that routine will be called
every time we need to compute a time stamp. It should not expect any
parameter, and should return a string.
All the channels go to the specified files. If a channel is not configured, it
is redirected to 'error', or STDERR if no 'error' channel was configured
either.
Two channels not opened via a magic open and whose logfile
name is the same are effectively shared, i.e. the same file
descriptor is used for both of them. If you supply distinct rotation
policies (e.g. by having a default policy, and supplying another policy to
one of the channel only), then the final rotation policy will depend on
which one was opened first. So don't do that.
Beware of chdir(). If your program uses chdir(), you should always
specify logfiles by using absolute paths, otherwise you run the risk of having
your relative paths become invalid: there is no anchoring done at the time you
specify them. This is especially true when configured for rotation, since the
logfiles are recreated as needed and you might end up with many logfiles
scattered throughout all the directories you chdir()ed to.
Logging channels with the same pathname are shared, i.e. they are
only opened once by
"Log::Agent::Driver::File". Therefore, if
you specify different rotation policy to such channels, the channel opening
order will determine which of the policies will be used for all such shared
channels. Such errors are flagged at runtime with the following message:
Rotation for 'logfile' may be wrong (shared with distinct policies)
emitted in the logs upon subsequent sharing.
Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>,
currently maintained by Mark Rogaski <mrogaski@cpan.org>.
Thanks to Joseph Pepin for suggesting the file permissions
arguments to make().
Copyright (C) 1999 Raphael Manfredi. Copyright (C) 2002 Mark Rogaski; all rights
reserved.
See Log::Agent(3) or the README file included with the
distribution for license information.
Log::Agent::Driver(3), Log::Agent(3),
Log::Agent::Rotate(3).
Visit the GSP FreeBSD Man Page Interface. Output converted with ManDoc.
|