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) is associated with an arbitrary name. This name can be used to bypass log distribution and log only in the named mechanism.

If you have 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).

Log levels are modeled after syslog:

  log level       description
  =====================================================
  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 omitted level defaults to PL_NOTICE.

Scope is defined with the following characters:

  character       definition
  =====================================================
  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 omitted scope defaults to PL_GE.

Only the first two arguments are mandatory. What you put into the %options, and whether you need it at all, will depend on the mechanism you're using. The facilities provided directly by Paranoid are as follows:

  mechanism        arguments
  =====================================================
  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.

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. If you have PDebug enabled as a mechanism this function can also provide an equivalent sprintf functionality using the additional arguments, and that processed output will be shared with all other mechanisms that are enabled.

NOTE: PDebug support is meant to be a convenience to unify both normal logging and the Paranoid::Debug::pdebug STDERR tracing mechanism. That said, note than enabling it means that all log messages are passed to pdebug, since it has its own mechanism for deciding what gets sent to STDERR or not.

PDebug support may not make sense for if your logging and debug output can't be neatly lined up with the syslog-styled severities.

plverbosity

    $rv = plverbosity($level);

This function provides a simpler way to enable Stdout/Stderr logging to 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.

This is primarily a convenience function for those simple, non-interactive programs/functions that need support varying levels of verbosity for the console. From that perspective, it will be 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.