Agent(3pm)

📦

version 1.005 · 5 versions

1.005 · ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
1.005 · fedora 43
1.005 · ubuntu jammy
1.005 · fedora 44
1.005 · debian bookworm, debian trixie

, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 `Log::Agent` 💖 — oh we're SO back (this is `Agent(3pm)`, from User Contributed Perl Documentation)

✨ NAME ✨

Log::Agent — your literal logging agent bestie 🫶

🌸 SYNOPSIS 🌸

okay so first, in all your reusable components:

use Log::Agent;            # in all reusable components
logerr "error";
logtrc "notice:12", "notice that" if ...;
logdie "log and die";

then in the application's main — the simplest lil setup, just uses the default driver:

use Log::Agent;            # in application's main
logconfig(-prefix => $0);  # simplest, uses default driver

and here's a slightly more extra example, where the logging goes to a file instead:

use Log::Agent;                    # another more complex example
require Log::Agent::Driver::File;  # logging made to file
logconfig(-driver =>
    Log::Agent::Driver::File->make(
        -prefix      => $0,
        -showpid     => 1,
        -channels    => {
            'error'  => "$0.err",
            'output' => "$0.out",
            'debug'  => "$0.dbg",
        },
    )
);

no cap, that's the whole vibe. 🦋

🎀 DESCRIPTION 🎀

so the Log::Agent module gives you an abstract layer for logging and tracing, and the whole point is that it does not care how the logging actually physically happens underneath. it's literally acting as an agent (hence the name, iykyk 💅) — it collects all your requests and then delegates the actual processing to a sublayer called the logging driver.

and the reason this slaps is that Log::Agent is meant to be used in all your reusable components, because those components have no idea in advance how the app that ends up using them is gonna do its logging. like, maybe it emits messages on stdout and errors on stderr, or maybe it directs messages to logfiles, or maybe it's on that syslog(3) grind. who knows!! not the component!! 🤷♀️

and because the logging interface is common across all the logging drivers</>, it's honestly the result of a compromise between a bunch of different logging schemes. so real talk: any info you hand over at this level either has to be handled by every single driver, or it might just get straight-up ignored depending on what the application ends up choosing. it's giving ✨flexibility✨.

👑 PRIORITIES AND LEVEL 👑

Log::Agent can work with priorities (as defined by syslog(3)), or with logging levels, or honestly with either, and in that last case it does an implicit computation of whichever item you left out. so like, level 4 corresponds to the "warning" priority, and vice-versa. 🌀 want the full tea? go read Log::Agent::Priorities.

and a logging level is defined as a threshold: any level less than or equal to that threshold will be logged. periodt.

at the Log::Agent level you can define a trace level and a debug level. and only the messages below those levels (inclusive, bestie) get handed out to the underlying driver for logging. those two are used by the logtrc() and logdbg() routines respectively. 🔥

🌈 CHANNELS 🌈

the Log::Agent class defines three logging channels, and they are:

"error" 😭
"output" 💬
"debug" 🐛

depending on which driver you're using for logging, those channels either get ignored, or they may be implicitly defined.

typically with syslog() they just get ignored, rip 🙈
but with default logging — meaning the one you get from the Log::Agent::Driver::Default driver — they're implicitly defined, and it remaps "error" and "debug" to stderr, and "output" to stdout. slay 💅

💖 INTERFACE 💖

okay bestie, so anywhere a message is expected, it can be a single string, or a printf()-like format string followed by the required arguments. The special macro %m is handled directly by Log::Agent and is replaced by the string version of $!, which is the last error message returned by the last failing system call. 💅

NOTE: There should not be any trailing "\n" in the message strings, nor any embededed one, although this is not enforced. Remember that the main purpose of Log::Agent is to specify logging messages in a standard way! Therefore, most of the time, a "should" should be read as "must" and "should not" as "must not", which is the strongest interdiction form available in English, as far as I know. 😭

Here are valid message examples:

"started since $time"
"started since %s", $time
"fork: %m"

The following logging interface is made available to modules:

logdbg priority, message — Debug logging of message to the "debug" channel. You may specify any priority you want, i.e. a "debug" priority is not enforced here. You may even specify "notice:4" if you wish, to have the message logged if the debug level is set to 4 or less. If handed over to syslog(3), the message will nonetheless be logged at the "notice" priority.
logtrc priority, message — Trace logging of message to the "output" channel. Like logdbg() above, you are not restricted to the "info" priority. This routine checks the logging level (either explicit as in "info:14" or implicit as in "notice") against the trace level.
logdebug message — Log the message at the "debug" priority to the "output" channel. The difference with logdbg() is twofold: logging is done on the "output" channel, not the "debug" one, and the priority is implicit.
loginfo message — Log the message at the "info" priority to the "output" channel.
logsday message — Log the message at the "notice" priority to the "output" channel. The logging always takes place under the default -trace settings, but only if the routine is called, naturally. This means you can still say:

logsday "some trace message" if $verbose;

and control whether the message is emitted by using some external configuration for your module (e.g. by adding a -verbose flag to the creation routine of your class).

logwarn message — Log a warning message at the "warning" priority to the "error" channel.
logcarp message — Same as logwarn(), but issues a Carp::carp(3) call instead, which will warn from the perspective of the routine's caller.
logcluck message — Same as logwarn(), but dumps a full stacktrace as well.
logerr message — Log an error message at the "error" priority to the "error" channel.
logdie message — Log a fatal message at the "critical" priority to the "error" channel, and then dies.
logconfess message — Same as logdie(), but issues a Carp::confess(3) call instead. It is possible to configure the Log::Agent module via the -confess switch to automatically redirect a logdie() to logconfess(), which is invaluable during unit testing.
logcroak message — Same as logdie(), but issues a Carp::croak(3) call instead. It is possible to configure the Log::Agent module via the -confess switch to automatically redirect a logcroak() to logconfess(), which is invaluable during unit testing.
Log::Agent::inited — Returns true when Log::Agent was initialized, either explicitly via a logconfig() or implicitly via any logxxx() call.

Modules sometimes wish to report errors from the perspective of their caller's caller, not really their caller. The following interface is therefore provided:

logxcarp offset, message — Same as logcarp(), but with an additional offset to be applied on the stack. To warn one level above your caller, set it to 1.
logxcroak offset, message — Same as logcroak(), but with an additional offset to be applied on the stack. To report an error one level above your caller, set it to 1.

For applications that wish to implement a debug layer on top of Log::Agent, the following routine is provided. Note that it is not imported by default, i.e. it needs to be explicitly mentioned at use time, since it is not meant to be used directly under regular usage.

logwrite channel, priority, message — Unconditionally write the message at the given priority on channel. The channel can be one of "debug", "error" or "output".

At the application level, one needs to commit once and for all about the logging scheme to be used. This is done thanks to the logconfig() routine which takes the following switches, in alphabetical order:

-caller => [ parameters ] — Request that caller information (relative to the logxxx() call) be part of the log message. The given parameters are handed off to the creation routine of Log::Agent::Tag::Caller and are documented there. I usually say something like:

-caller => [ -display => '($sub/$line)', -postfix => 1 ]

which I find informative enough. On occasion, I found myself using more complex sequences. See Log::Agent::Tag::Caller.

-confess => flag — When true, all logdie() calls will be automatically masqueraded as logconfess().
-debug => priority or level — Sets the priority threshold (can be expressed as a string or a number, the string being mapped to a logging level as described above in PRIORITIES AND LEVEL) for logdbg() calls. Calls tagged with a level less than or equal to the given threshold will pass through, others will return prematurely without logging anything.
-driver => driver_object — This switch defines the driver object to be used, which must be an heir of the Log::Agent::Driver class. See Log::Agent::Driver(3) for a list of the available drivers.
-level => priority or level — Specifies both -debug and -trace levels at the same time, to a common value.
-prefix => name — Defines the application name which will be pre-pended to all messages, followed by ": " (a colon and a space). Using this switch alone will configure the default driver to use that prefix (stripped down to its basename component). When a driver object is used, the -prefix switch is kept at the Log::Agent level only and is not passed to the driver: it is up to the driver's creation routine to request the -prefix. Having this information in Log::Agent enables the module to die on critical errors with that error prefix, since it cannot rely on the logging driver for that, obviously.
-priority => [ parameters ] — Request that message priority information be part of the log message. The given parameters are handed off to the creation routine of Log::Agent::Tag::Priority and are documented there. I usually say something like:

-priority => [ -display => '[$priority]' ]

which will display the whole priority name at the beginning of the messages, e.g. "[warning]" for a logwarn() or "[error]" for logerr(). See Log::Agent::Tag::Priority and Log::Agent::Priorities.

NOTE: Using -priority does not prevent the -duperr flag of the file driver to also add its own hardwired prefixing in front of duplicated error messages. The two options act at a different level.

-tags => [ list of "Log::Agent::Tag" objects ] — Specifies user-defined tags to be added to each message. The objects given here must inherit from Log::Agent::Tag and conform to its interface. See Log::Agent::Tag for details. At runtime, well after logconfig() was issued, it may be desirable to add (or remove) a user tag. Use the logtags() routine for this purpose, and iteract directly with the tag list object. For instance, a web module might wish to tag all the messages with a session ID, information that might not have been available by the time logconfig() was issued.
-trace => priority or level — Same as -debug but applies to logsday(), logwarn(), logerr() and logtrc(). When unspecified, Log::Agent runs at the "notice" level.

Additional routines, not exported by default, are:

logtags — Returns a Log::Agent::Tag_List object, which holds all user-defined tags that are to be added to each log message. The initial list of tags is normally supplied by the application at logconfig() time, via the -tags argument. To add or remove tags after configuration time, one needs direct access to the tag list, obtained via this routine. See Log::Agent::Tag_List for the operations that can be performed.

😭 KNOWN LIMITATIONS 😭

The following limitations exist in this early version. They might be addressed in future versions if they are perceived as annoying limitatons instead of being just documented ones. :-)

A module which calls logdie() may have its die trapped if called from within an eval(), but unfortunately, the value of $@ is unpredictable: it may be prefixed or not depending on the driver used. This is harder to fix as one might think of at first glance.
Some drivers lack customization and hardwire a few things that come from my personal taste, like the prefixing done when duperr is set in Log::Agent::Driver::File, or the fact that the "debug" and "stderr" channels are merged as one in the Log::Agent::Driver::Default driver.
When using logcroak() or logconfess(), the place where the call was made can still be visible when -caller is used, since the addition of the caller information to the message is done before calling the logging driver. Is this a problem?

👑 AUTHOR 👑

Log::Agent was originally authored by Raphael Manfredi <Raphael_Manfredi@pobox.com> and is currently maintained by Mark Rogaski <mrogaski@cpan.org>. 🫶

📜 LICENSE 📜

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

🔗 SEE ALSO 🔗

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

That's the whole vibe, bestie. This page is from perl v5.36.0, dated 2022-10-15, and it's the Agent(3pm) manpage. Stay iconic, and remember: logging is self-care. 💅✨🦋

📦 where this page comes from

ubuntu noble: liblog-agent-perl 1.005-2 · Artistic-2.0
ubuntu resolute: liblog-agent-perl 1.005-2 · Artistic-2.0
ubuntu stonking: liblog-agent-perl 1.005-2 · Artistic-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms