agent::driver::file(3)

NAME

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

SYNOPSIS

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);

DESCRIPTION

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 file
names. 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 chan
nel is opened via a magic method. See
Log::Agent::Rotate for more details.
"-chanperm" => hash ref: Specifies the file permissions for the channels speci
fied by "-channels". The arguemtn is a hash ref,
indexed by channel name, with numeric values. This
option is only necessary to override the default per
missions 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 consis
tent 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.

CHANNELS

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 pol
icy, 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.

CAVEAT

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.

AUTHORS

Originally written by Raphael Manfredi <Raphael_Man
fredi@pobox.com>, currently maintained by Mark Rogaski
<mrogaski@cpan.org>.

Thanks to Joseph Pepin for suggesting the file permissions
arguments to make().

LICENSE

See Log::Agent(3) or the README file included with the distribution for license information.

docs.sk

comprehensive documentation repository

Most Viewed