Paranoid::Log(3pm)

📦
version 2.10 · 3 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Paranoid::Log — the log functions, bestie. It's the Paranoid::Log page from the User Contributed Perl Documentation, and it's genuinely iconic.

⭐ VERSION ⭐

$Id: lib/Paranoid/Log.pm, 2.10 2022/03/08 00:01:04 acorliss $

✨ SYNOPSIS ✨

use Paranoid::Log;

$rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });
$rv = stopLogger($name);

$rv = plog($severity, $message);

$rv = plverbosity(3);

🦋 DESCRIPTION 🦋

So Paranoid::Log is a whole logging and message-distribution framework, and it's modeled heavily on syslog. Like, it follows syslog's whole thing: you log messages at different levels of severity, and those messages get distributed across multiple log mechanisms automatically. No manual forwarding, it just happens. Slay.

Inside the Paranoid distribution itself, it supports logging to files, STDERR, and named buffers. Additional modules exist on CPAN so you can distribute to e-mail, syslog, and more. And honestly? Writing your own log mechanism to work with this framework is relatively trivial. Go off, DIY queen.

🎀 IMPORT LISTS 🎀

By default, this module exports these symbols:

PL_DEBUG PL_INFO PL_NOTICE PL_WARN PL_ERR PL_CRIT
PL_ALERT PL_EMERG PL_EQ PL_NE PL_GE PL_LE
startLogger stopLogger plog plverbosity

And there's also this specialized import list:

List        Members
--------------------------------------------------------
all         @defaults

💅 LOGGING MECHANISMS 💅

Every logging mechanism is its own separate module made of non-exported functions that all conform to a consistent API. Each mechanism module must have these functions:

Function        Description
------------------------------------------------------
init            Called when module first loaded
addLogger       Add a named instance of the mechanism
delLogger       Removes a named instance of the mechanism
logMsg          Logs the passed message

The init function gets called exactly once — the first time the module is used and accessed. No arguments are passed to it, and if a particular mechanism doesn't need it, it can just return a boolean true and call it a day.

The logMsg function is the one that actually hands a log message over to the mechanism. It's called with a record hash based on this template:

my %record  = (
    name      => $name,
    mechanism => $name,
    msgtime   => time,
    severity  => $level,
    scope     => $scope,
    message   => $message,
    options   => {},
    );

The options key is a hash reference to any logger-specific options — for when the mechanism needs one.

The addLogger function gets called whenever a logger is started. It's called with the logger record above, minus a message and msgtime.

The delLogger function gets called whenever a logger is stopped. It's also called with the logger record above, minus a message and msgtime.

Want a simple example of a mechanism module? Go peek at the source for Paranoid::Logger::File. 💖

🔥 SUBROUTINES/METHODS 🔥

startLogger

$rv = startLogger($name, $mechanism, PL_WARN, PL_GE, { %options });

This function enables the specified logging mechanism at the specified levels. Each mechanism (or permutation of one) gets associated with an arbitrary name. That name can then be used to bypass log distribution and log only in the named mechanism.

And if you've got your own custom mechanism that complies with the Paranoid::Log calling conventions, you can pass this the name of the module (for example, MyLog::Foo). Look at you, building your own.

Log levels are modeled after syslog:

  • PL_EMERG — system is unusable
  • PL_ALERT — action must be taken immediately
  • PL_CRIT — critical conditions
  • PL_ERR — error conditions
  • PL_WARN — warning conditions
  • PL_NOTICE — normal but significant conditions
  • PL_INFO — informational
  • PL_DEBUG — debug-level messages

If level is omitted, it defaults to PL_NOTICE.

Scope is defined with these characters:

  • PL_EQ — log only messages at this severity
  • PL_GE — log only messages at this severity or higher
  • PL_LE — log only messages at this severity or lower
  • PL_NE — log at all levels but this severity

If scope is omitted, it defaults to PL_GE.

Lowkey the best part: only the first two arguments are mandatory. What you drop into %options, and whether you even need it, depends entirely on the mechanism you're using. The facilities provided directly by Paranoid are:

  • Stdout — none
  • Stderr — none
  • Buffer — bufferSize (optional)
  • File — file, mode (optional), perm (optional), syslog (optional)
  • PDebug — none

stopLogger

$rv = stopLogger($name);

Removes the specified logging mechanism from the configuration and re-initializes the distribution processor. It's giving… closure. 🫶

plog

$rv = plog($severity, $message);

# If the PDebug mechanism is enabled
$rv = plog($severity, $message, @substitutions);

This call logs the passed message to all facilities enabled at the specified log level. And if you've got PDebug enabled as a mechanism, this function can also provide equivalent sprintf functionality using the additional arguments — and that processed output gets shared with all the other mechanisms that are enabled. One glow-up, everyone benefits.

NOTE: PDebug support is meant to be a convenience to unify both normal logging and the Paranoid::Debug::pdebug STDERR tracing mechanism. That said, heads up: enabling it means all log messages are passed to pdebug, since it has its own mechanism for deciding what gets sent to STDERR or not. Also, PDebug support may not make sense for you if your logging and debug output can't be neatly lined up with the syslog-styled severities. Know thyself. 💅

plverbosity

$rv = plverbosity($level);

This function gives you a simpler way to enable Stdout/Stderr logging at the appropriate level — if you consider PL_DEBUG to PL_NOTICE to be normal operation messages appropriate for STDOUT messages, and PL_WARN through PL_EMERG to be error messages appropriate for STDERR.

It's primarily a convenience function for those simple, non-interactive programs/functions that need to support varying levels of verbosity for the console. From that perspective, it's assumed that all user notifications would be simple one-line messages.

NOTE: PL_EMERG and PL_ALERT are always enabled if you use this function. Any error messages that should always be printed to the console regardless of verbosity settings should be sent to one of those two levels. The remaining levels (PL_WARN through PL_CRIT) will be optionally enabled, just like PL_DEBUG through PL_NOTICE.

🌈 DEPENDENCIES 🌈

  • Paranoid::Debug
  • Paranoid::Input
  • Paranoid::Module

🌸 EXAMPLES 🌸

This example provides the following behavior: debug messages go to a file, notice & above messages go to syslog, and critical and higher messages also go to console and e-mail.

# Set up the logging facilities
startLogger("debug-log", "File", PL_DEBUG, PL_GE,
  { file => '/var/log/myapp-debug.log' });
startLogger("console-err", "Stderr", PL_CRIT, PL_GE);

# This goes only to the debug log
plog(PL_DEBUG, "Starting application");

# Again, only the debug log
plog(PL_NOTICE, "Uh, something happened...");

# This goes to STDERR and the debug log
plog(PL_EMERG, "Ack! <choke... silence>");

👑 SEE ALSO 👑

  • Paranoid::Log::Buffer
  • Paranoid::Log::File

💀 BUGS AND LIMITATIONS 💀

Nothing listed here. The section exists, but it's empty — no known bugs, no limitations documented on this page. (Not a single complaint. Queen behavior.)

🧚 AUTHOR 🧚

Arthur Corliss (corliss@digitalmages.com)

This software is free software. Similar to Perl, you can redistribute it and/or modify it under the terms of either:

  1. the GNU General Public License

https://www.gnu.org/licenses/gpl-1.0.html

as published by the Free Software Foundation

http://www.fsf.org/

; either version 1

https://www.gnu.org/licenses/gpl-1.0.html

, or any later version

https://www.gnu.org/licenses/license-list.html#GNUGPL

, or

  1. the Artistic License 2.0

https://opensource.org/licenses/Artistic-2.0

,

subject to the following additional term: No trademark rights to "Paranoid" have been or are conveyed under any of the above licenses. However, "Paranoid" may be used fairly to describe this unmodified software, in good faith, but not as a trademark.

(c) 2005 - 2020, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2020, Paranoid Inc. (www.paranoid.com)

okay that's the whole page, bestie — every flag, every mechanism, every record key, all of it. mwah 💖

this was Paranoid::Log(3pm), perl v5.38.2, dated 2024-03-07 — periodt, stay logged ✨

📦 where this page comes from