Net::C...Logger(3pm)

💖 Net::C...Logger 💖

the manual page for Net::CLI::Interact::Logger — part of the User Contributed Perl Documentation, bestie. it's giving ✨per-instance, multi-target logging, with categories✨ and honestly? obsessed.

---

🌸 NAME 🌸

Net::CLI::Interact::Logger — per-instance multi-target logging, with categories 🎀

---

✨ SYNOPSIS ✨

$logger->log($category, $level, @message);

that's it. that's the whole vibe. 🫶

---

🦋 DESCRIPTION 🦋

okay so this module is a generic logging service, built on top of Log::Dispatch but with extra options and config sprinkled on top, periodt.

here's the deal: log messages coming from your app get categorized, and every single category can be switched on or off by itself, and each one gets its own log level (like "emergency" all the way down to "debug"). and if you want, you can slap high resolution timestamps onto those messages too. iconic. ⭐

---

🌈 DEFAULT CONFIGURATION 🌈

because it's based on Log::Dispatch::Config, this logger can have multiple targets, and each one gets configured with its own independent level threshold. no cap.

the overall default config? it prints log messages to the screen (console), with a minimum level of "debug". and each category (more on that below 👇) has its own log level too.

🚨 bestie listen — categories are arbitrary, so if a category isn't explicitly enabled or disabled, it's assumed to be disabled. if you wanna invent a brand new category for your app, literally just think of the name and start using it, with a $level and @message exactly like in the SYNOPSIS up there. go off. 💅

---

👑 INTERFACE 👑

💜 log( $category, $level, @message )

the combo of category + level is what decides whether the log messages get emitted to any of the log destinations. destinations get set with the "log_config" method, and categories get configured with the "log_flags" method. iykyk.

the @message list gets joined by a space character, and a newline gets appended if the last message doesn't already contain one itself. then messages are prepended with the first character of their $category, and indented proportionally to their $level. the way that it formats... 🎀

🧚 log_config( %config )

this takes a "Log::Dispatch::Config" configuration (a hash ref, bestie), which means multiple log targets can be specified with different minimum level thresholds. there's a default config that emits messages to your screen (console) with no minimum threshold:

{
    dispatchers => ['screen'],
    screen => {
        class => 'Log::Dispatch::Screen',
        min_level => 'debug',
    },
};

slay. 🫶

🌸 log_flags( @categories | %category_level_map )

you (yes, you) are expected to specify which log categories you care about, and at what levels. and here's the important bit: if a category gets used for logging in the app but was never specified, it's deemed disabled. so even though the default destination log level is "debug", no messages are emitted until a category is enabled. not a single one. 💀

in the array reference form, the list should contain category names, and they'll all be mapped to the "error" level:

$logger->log_flags([qw/
    network
    disk
    io
    cpu
/]);

in the hash reference form, the keys should be category names and the values are log levels from this list below — ordered so that each level "includes" the levels above it:

emergency
alert
critical
error
warning
notice
info
debug

for example:

$logger->log_flags({
    network => 'info',
    disk    => 'debug',
    io      => 'critical',
    cpu     => 'debug',
});

messages at or above the specified level get passed on to the "Log::Dispatch" target, which may then specify its own overriding threshold. two thresholds, one message. main character energy. ✨

🔥 Net::CLI::Interact->default_log_categories() 🔥

not a part of this class, okay, but it's the only way to retrieve a list of the current log categories used in the Net::CLI::Interact distribution source. and heads up: it does not take into account any log categories added by the user. sorry bestie, them's the rules. 🙈

⭐ log_stamp( $boolean )

enable (this is the default) or disable the display of high resolution interval timestamps with each log message. 🕐

🎀 log_category( $boolean )

enable (again, the default) or disable the display of the first letters of the category name with each log message. cute little initial, we love her. 💅

🦋 log_start( [$seconds, $microseconds] )

the time of the start for generating a time interval when logging stamps. it defaults to the result of "Time::HiRes::gettimeofday" at the point the module gets loaded, in list context. ⏱️

💖 would_log( $category, $level )

returns True if, according to the current "log_flags", the given $category is enabled at or above the threshold of $level. otherwise it returns False. and note — the "Log::Dispatch" targets maintain their own thresholds as well. 👀

---

🌟 reminder reminder: that "Log::Dispatch" threshold thing goes both ways, bestie. this method says yes, the target might still say no. keep it in mind. 💜

---

that's the whole page, angel. go log something gorgeous. 🌈

this has been the Net::C...Logger page, from perl v5.36.0, dated 2023-10-28 — mwah, take care of her, she's iconic 💅✨🎀