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

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

💖 NAME 💖

Log::Agent::Channel::File — bestie, this is the file logging channel for Log::Agent. It writes your logs to a whole actual file. So iconic of it. ✨

This one lives in the Agent:...::File(3pm) corner of the perl universe, filed under User Contributed Perl Documentation, and it's giving very much "your logs, but make them a file" energy. 🎀

✨ SYNOPSIS ✨

require Log::Agent::Channel::File;

my $driver = Log::Agent::Channel::File->make(
    -prefix     => "prefix",
    -stampfmt   => "own",
    -showpid    => 1,
    -magic_open => 0,
    -filename   => "/tmp/output.err",
    -fileperm   => 0640,
    -share      => 1,
);

Like… that's it. That's the whole vibe check. 💅

🌸 DESCRIPTION 🌸

The file channel does the logging-to-a-file thing, and it also handles all the necessary prefixing and stamping of the messages for you. So you don't have to. You're welcome. 🫶

Internally, the Log::Agent::Driver::File driver creates objects like this for each logging channel that gets defined when the driver is created. No cap.

The creation routine make() takes these arguments, and yes we're going through all of them:

  • -filename => file — the file name where output should go. Bestie listen: the file is opened in append mode and autoflushing is turned on. Also go peek at the -magic_open flag while you're here. 👀
  • -fileperm => perm — the permissions the file should be opened with (XOR'd with the user's umask, so, like, your umask gets a say too). Due to the nature of the underlying open() and sysopen(), the value is limited to less than or equal to 0666. See "umask" in perlfunc(3) for more details. Don't fight it, it's just how it is. 💀
  • -magic_open => flag — when true, channel filenames beginning with '>' or '|' get opened using Perl's open(). Otherwise sysopen() is used, in append mode.

Default is false.

  • -no_newline => flag — when set to true, never append any "\n" (on Unix) or "\r\n" (on Windows) to log messages.

Internally, Log::Agent relies on the channel to delimit logged lines appropriately, so this flag is not used. However, it might be useful for "Log::Agent::Logger" users.

Default is false, meaning newline markers are systematically appended.

  • -no_prefixing => flag — when set to true, disable the prefixing logic entirely, i.e. the following options are ignored completely: -prefix, -showpid, -no_ucfirst, -stampfmt. They simply do not get a seat at the table. 🚫

Default is false.

  • -no_ucfirst => flag — when set to true, don't upper-case the first letter of the log message entry when there's no prefix inserted before the logged line. When there is a prefix, a ":" character follows, and therefore the leading letter of the message should not be upper-cased anyway. See the logic? Slay.

Default is false, meaning uppercasing is performed.

  • -prefix => prefix — the application prefix string to prepend to messages. Prepend. At the front. The main character position. 👑
  • -rotate => object — this sets a default logfile rotation policy. You need to install the additional Log::Agent::Rotate module to use this switch, so, like, go get it first bestie.

object is the Log::Agent::Rotate instance describing the rotating policy for the channel. Only files which are not opened via a so-called magic open can be rotated. Magic files don't rotate. Periodt.

  • -share => flag — when true, this flag records the channel in a global pool indexed by filenames. An existing file handle for the same filename may then be shared amongst several file channels. Sharing is caring etc.

However, you will get this message in the file

Rotation for 'filename' may be wrong (shared with distinct policies)

when a rotation policy different from the one used during the initial opening is given. Which policy will be used is unspecified, on purpose. They did that intentionally. It's not a bug, it's a choice. 🫠

  • -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. See Log::Agent::Stamping for a description of the available format names.

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. Simple as that. ✨

😭 CAVEAT 😭

Beware of chdir(). Okay this one's important, bestie, lean in.

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. A whole trail of chaos. 🙈

fr fr, absolute paths only. Future you will be obsessed with past you for it. 💖

👑 AUTHORS 👑

Originally written by Raphael Manfredi <Raphael_Manfredi@pobox.com>, currently maintained by Mark Rogaski <mrogaski@cpan.org>. Legends, honestly. 🌟

📜 LICENSE 📜

Copyright (C) 1999 Raphael Manfredi. Copyright (C) 2002 Mark Rogaski, mrogaski@cpan.org; all rights reserved.

See Log::Agent(3) or the README file included with the distribution for license information. Read it, it's short, it's giving responsible citizen. 🎀

🌈 SEE ALSO 🌈

And that's the whole page, bestie — no notes. This was perl v5.36.0, dated 2022-10-15, straight from the User Contributed Perl Documentation archives. Byeee 🦋💜

📦 where this page comes from