Agent:...r::File(3pm)

📦
version 1.005 · 5 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

Log::Agent::Driver::File — bestie, this is the file logging driver for Log::Agent 💖 That's the whole thing. She logs to files. She's iconic. Periodt.

✨ 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 🦋

okay so here's the tea 🫖 — this driver takes all your logxxx() operations and redirects them to specific files, usually one file per channel (but lowkey channels can all point at the same file, no judgement).

The creation routine make() takes the following arguments:

  • -channels => hash ref — this is where you tell her where the channels go. The hash you supply 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 you can do stuff like this:
-channels => {
    'error'   => '>&FILE',
    'output'  => '>newlog',   # recreate each time, don't append
    'debug'  => '|mailx -s whatever user',
}

If a channel (like say output) isn't specified, it'll go to the error channel instead, and if that one isn't specified either, it goes to STDERR. no cap. 💀

If you've installed the extra Log::Agent::Rotate module, you can also override any default rotating policy setup via the -rotate argument: instead of handing over the channel as a single string, you 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 example above, the rotation policy for the debug channel will not be activated, because that channel gets opened via a magic method. See Log::Agent::Rotate for more details.

  • -chanperm => hash ref — this one sets the file permissions for the channels specified by -channels. The argument is a hash ref, indexed by channel name, with numeric values. You only need this option to override the default permissions used by Log::Agent::Channel::File. Honestly it's generally better to leave these permissive and let the user's umask do its thing. See "umask" in perlfunc(3) for more details..
  • -duperr => flag — when true, all messages normally sent to the error channel also get copied over to the output channel, with a prefix slapped on so you can clearly tell what's what: "FATAL: " for logdie(), logcroak() and logconfess(), "ERROR: " for logerr() and "WARNING: " for logwarn().

Heads up though: the "duplicate" is the original error string for logconfess() and logcroak(), and it 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. one file, all the drama. 👑
  • -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. your little signature. ✨
  • -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. like a little name tag for your process 🎀

Default is false.

  • -stampfmt => (name | CODE) — specifies the time stamp format to use. By default, my own format is used. Here are the formats on offer:
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. And if you supply distinct rotation policies (like, say, you have a default policy and then hand another policy to just one of the channels), then the final rotation policy will depend on which one was opened first. So don't do that. fr fr. 🚫

💀 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. it's giving chaos bestie 😭

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_Manfredi@pobox.com>, currently maintained by Mark Rogaski <mrogaski@cpan.org>.

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

👑 LICENSE 👑

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.

⭐ SEE ALSO ⭐

Log::Agent::Driver(3), Log::Agent(3), Log::Agent::Rotate(3).

aaaand that's the whole page, bestie 💅 this little Agent:...r::File(3pm) writeup is living in perl v5.36.0, dated 2022-10-15 — iconic, timeless, no cap. go log something. 🦋💖

📦 where this page comes from