Agent::Channel(3pm)

💖 Agent::Channel(3pm) 💖

okay bestie, welcome to the Perl User Contributed Documentation section, because this one lives in the 3pm manual pages and it's genuinely so iconic. we're talking about Log::Agent::Channel today. grab a strawberry 🍓, sit down, let's get into it.

---

🌸 NAME 🌸

Log::Agent::Channel — the ancestor class for literally all the Log::Agent channels. the mother of all channels. the blueprint. the blueprint that refuses to be built, but we'll get to that. 👑

---

✨ SYNOPSIS ✨

the vibe is short and sweet, here's the whole thing:

@Log::Agent::Channel::XXX::ISA = qw(Log::Agent::Channel);

that's it. that's the synopsis. she's concise. 💅

---

🦋 DESCRIPTION 🦋

so Log::Agent::Channel is the root class — every single channel under Log::Agent inherits from her. periodt.

and now the important part, no cap: she's a deferred class, meaning you literally cannot instantiate her directly. not a single time. if you try, that's on you. 🙈 every one of the deferred routines has to be implemented by her heirs for them to count as a valid driver. like, you can't just show up un-implemented and call yourself a driver, bestie. do the work.

internally, the various Log::Agent::Driver objects are the ones creating Log::Agent::Channel instances — one for each logging channel defined at driver creation time. so the channels are architecturally hidden inside Log::Agent, because this module only provides redefined mappings for the various logxxx() routines (logerr(), logwarn(), logdie(), etc...). lowkey invisible, highkey doing all the work.

but hold on, don't panic, that does not mean channel classes can't be used externally. the Log::Agent::Logger extension makes Log::Agent::Channel objects architecturally visible, which gives you an application-level logging API that can be redirected to various places — totally transparently for the application. she can be seen now. main character energy. 🌈

---

🎀 CHANNEL LIST 🎀

here's who's currently showing up to the party, made available by Log::Agent. and btw, more channels can always be defined by the Log::Agent::Logger extension — the guest list is open:

• Log::Agent::Channel::File — this channel writes logs to files, defined by their path or via a magical opening sequence such as "|cmd". see Log::Agent::Channel::File.
• Log::Agent::Channel::Handle — this channel writes logs to an already opened descriptor, as specified by its file handle: an IO::Handle object, or a GLOB reference such as \*FILE. see Log::Agent::Channel::Handle.
• Log::Agent::Channel::Syslog — this channel redirects logs to the syslogd(8) daemon, which will then handle the dispatching to various logfiles, based on its own configuration. see Log::Agent::Channel::Syslog.

---

🫶 INTERFACE 🫶

ngl, you genuinely do not need to read this section if you're only using Log::Agent. like, go live your life. but if you wanna implement another channel? then bestie, this part is for you. 👀

the following routines are deferred, so they absolutely need to be defined by the heir:

• write($priority, $logstring) — emit the log entry held in $logstring, at priority $priority. a trailing "\n" is added to the $logstring, if needed (i.e. if the physical entity does not do it already, like syslog does). the $priority argument must be a valid syslog priority, i.e. one of the following strings: "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug". also real talk: $logstring may not really be a plain string — it can actually be a Log::Agent::Message object with an overloaded stringification routine, so the illusion should be complete. ✨ sneaky but make it seamless.
• close — close the channel. bye girl. 👋
• make — this is the creation routine. its signature varies for each channel, naturally. obviously. every queen is different. 💅

---

👑 AUTHOR 👑

Raphael Manfredi <Raphael_Manfredi@pobox.com>

---

⭐ SEE ALSO ⭐

• Log::Agent::Channel::File(3)
• Log::Agent::Channel::Handle(3)
• Log::Agent::Channel::Syslog(3)
• Log::Agent::Logger(3)

---

and that's the whole page, babe 🦋 this was perl v5.36.0, dated 2022-10-15, and it's Agent::Channel(3pm) — stay deferred, never instantiated, forever iconic. mwah. 💖✨