Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Dispatchouli(3)  User Contributed Perl Documentation Log::Dispatchouli(3)

NAME
       Log::Dispatchouli - a simple wrapper around Log::Dispatch

VERSION
       version 2.012

SYNOPSIS
	 my $logger = Log::Dispatchouli->new({
	   ident     =>	'stuff-purger',
	   facility  =>	'daemon',
	   to_stdout =>	$opt->{print},
	   debug     =>	$opt->{verbose}
	 });

	 $logger->log([	"There are %s items left to purge...", $stuff_left ]);

	 $logger->log_debug("this is extra often-ignored debugging log");

	 $logger->log_fatal("Now we will die!!");

DESCRIPTION
       Log::Dispatchouli is a thin layer above Log::Dispatch and meant to make
       it dead simple to add logging to	a program without having to think much
       about categories, facilities, levels, or	things like that.  It is meant
       to make logging just configurable enough	that you can find the logs you
       want and	just easy enough that you will actually	log things.

       Log::Dispatchouli can log to syslog (if you specify a facility),
       standard	error or standard output, to a file, or	to an array in memory.
       That last one is	mostly useful for testing.

       In addition to providing	as simple a way	to get a handle	for logging
       operations, Log::Dispatchouli uses String::Flogger to process the
       things to be logged, meaning you	can easily log data structures.
       Basically: strings are logged as	is, arrayrefs are taken	as (sprintf
       format, args), and subroutines are called only if needed.  For more
       information read	the String::Flogger docs.

METHODS
   new
	 my $logger = Log::Dispatchouli->new(\%arg);

       This returns a new logger, a Log::Dispatchouli object.

       Valid arguments are:

	 ident	     - the name	of the thing logging (mandatory)
	 to_self     - log to the logger object	for testing; default: false
	 to_stdout   - log to STDOUT; default: false
	 to_stderr   - log to STDERR; default: false
	 facility    - to which	syslog facility	to send	logs; default: none

	 to_file     - log to PROGRAM_NAME.YYYYMMDD in the log path; default: false
	 log_file    - a leaf name for the file	to log to with to_file
	 log_path    - path in which to	log to file; defaults to DISPATCHOULI_PATH
		       environment variable or,	failing	that, to your system's tmpdir

	 file_format - this optional coderef is	passed the message to be logged
		       and returns the text to write out

	 log_pid     - if true,	prefix all log entries with the	pid; default: true
	 fail_fatal  - a boolean; if true, failure to log is fatal; default: true
	 muted	     - a boolean; if true, only	fatals are logged; default: false
	 debug	     - a boolean; if true, log_debug method is not a no-op
		       defaults	to the truth of	the DISPATCHOULI_DEBUG env var
	 quiet_fatal - 'stderr'	or 'stdout' or an arrayref of zero, one, or both
		       fatal log messages will not be logged to	these
		       (default: stderr)
	 config_id   - a name for this logger's	config;	rarely needed!

       The log path is either /tmp or the value	of the DISPATCHOULI_PATH env
       var.

       If the DISPATCHOULI_NOSYSLOG env	var is true, we	don't log to syslog.

   log
	 $logger->log(@messages);

	 $logger->log(\%arg, @messages);

       This method uses	String::Flogger	on the input, then logs	the result.
       Each message is flogged individually, then joined with spaces.

       If the first argument is	a hashref, it will be used as extra arguments
       to logging.  It may include a "prefix" entry to preprocess the message
       by prepending a string (if the prefix is	a string) or calling a
       subroutine to generate a	new message (if	the prefix is a	coderef).

   log_fatal
       This behaves like the "log" method, but will throw the logged string as
       an exception after logging.

       This method can also be called as "fatal", to match other popular
       logging interfaces.  If you want	to override this method, you must
       override	"log_fatal" and	not "fatal".

   log_debug
       This behaves like the "log" method, but will only log (at the debug
       level) if the logger object has its debug property set to true.

       This method can also be called as "debug", to match other popular
       logging interfaces.  If you want	to override this method, you must
       override	"log_debug" and	not "debug".

   set_debug
	 $logger->set_debug($bool);

       This sets the logger's debug property, which affects the	behavior of
       "log_debug".

   get_debug
       This gets the logger's debug property, which affects the	behavior of
       "log_debug".

   clear_debug
       This method does	nothing, and is	only useful for
       Log::Dispatchouli::Proxy	objects.  See Methods for Proxy	Loggers,
       below.

   set_muted
	 $logger->set_muted($bool);

       This sets the logger's muted property, which affects the	behavior of
       "log".

   get_muted
       This gets the logger's muted property, which affects the	behavior of
       "log".

   clear_muted
       This method does	nothing, and is	only useful for
       Log::Dispatchouli::Proxy	objects.  See Methods for Proxy	Loggers,
       below.

   get_prefix
	 my $prefix = $logger->get_prefix;

       This method returns the currently-set prefix for	the logger, which may
       be a string or code reference or	undef.	See Logger Prefix.

   set_prefix
	 $logger->set_prefix( $new_prefix );

       This method changes the prefix.	See Logger Prefix.

   clear_prefix
       This method clears any set logger prefix.  (It can also be called as
       "unset_prefix", but this	is deprecated.	See Logger Prefix.

   ident
       This method returns the logger's	ident.

   config_id
       This method returns the logger's	configuration id, which	defaults to
       its ident.  This	can be used to make two	loggers	equivalent in
       Log::Dispatchouli::Global so that trying	to reinitialize	with a new
       logger with the same "config_id"	as the current logger will not throw
       an exception, and will simply do	no thing.

   dispatcher
       This returns the	underlying Log::Dispatch object.  This is not the
       method you're looking for.  Move	along.

LOGGER PREFIX
       Log messages may	be prepended with information to set context.  This
       can be set at a logger level or per log item.  The simplest example is:

	 my $logger = Log::Dispatchouli->new( ... );

	 $logger->set_prefix("Batch 123: ");

	 $logger->log("begun processing");

	 # ...

	 $logger->log("finished	processing");

       The above will log something like:

	 Batch 123: begun processing
	 Batch 123: finished processing

       To pass a prefix	per-message:

	 $logger->log({	prefix => 'Sub-Item 234: ' }, 'error!')

	 # Logs: Batch 123: Sub-Item 234: error!

       If the prefix is	a string, it is	prepended to each line of the message.
       If it is	a coderef, it is called	and passed the message to be logged.
       The return value	is logged instead.

       Proxy loggers also have their own prefix	settings, which	accumulate.
       So:

	 my $proxy = $logger->proxy({ proxy_prefix => 'Subsystem 12: ' });

	 $proxy->set_prefix('Page 9: ');

	 $proxy->log({ prefix => 'Paragraph 6: ' }, 'Done.');

       ...will log...

	 Batch 123: Subsystem 12: Page 9: Paragraph 6: Done.

METHODS	FOR SUBCLASSING
   string_flogger
       This method returns the thing on	which flog will	be called to format
       log messages.  By default, it just returns "String::Flogger"

   env_prefix
       This method should return a string used as a prefix to find environment
       variables that affect the logger's behavior.  For example, if this
       method returns "XYZZY" then when	checking the environment for a default
       value for the "debug" parameter,	Log::Dispatchouli will first check
       "XYZZY_DEBUG", then "DISPATCHOULI_DEBUG".

       By default, this	method returns "()", which means no extra environment
       variable	is checked.

   env_value
	 my $value = $logger->env_value('DEBUG');

       This method returns the value for the environment variable suffix
       given.  For example, the	example	given, calling with "DEBUG" will check
       "DISPATCHOULI_DEBUG".

METHODS	FOR TESTING
   new_tester
	 my $logger = Log::Dispatchouli->new_tester( \%arg );

       This returns a new logger that logs only	"to_self".  It's useful	in
       testing.	 If no "ident" arg is provided,	one will be generated.
       "log_pid" is off	by default, but	can be overridden.

       "\%arg" is optional.

   events
       This method returns the arrayref	of events logged to an array in	memory
       (in the logger).	 If the	logger is not logging "to_self"	this raises an
       exception.

   clear_events
       This method empties the current sequence	of events logged into an array
       in memory.  If the logger is not	logging	"to_self" this raises an
       exception.

METHODS	FOR PROXY LOGGERS
   proxy
	 my $proxy_logger = $logger->proxy( \%arg );

       This method returns a new proxy logger -- an instance of
       Log::Dispatchouli::Proxy	-- which will log through the given logger,
       but which may have some settings	localized.

       %arg is optional.  It may contain the following entries:

       proxy_prefix
	   This	is a prefix that will be applied to anything the proxy logger
	   logs, and cannot be changed.

       debug
	   This	can be set to true or false to change the proxy's "am I	in
	   debug mode?"	 setting.  It can be changed or	cleared	later on the
	   proxy.

   parent
   logger
       These methods return the	logger itself.	(They're more useful when
       called on proxy loggers.)

METHODS	FOR API	COMPATIBILITY
       To provide compatibility	with some other	loggers, most specifically
       Log::Contextual,	the following methods are provided.  You should	not
       use these methods without a good	reason,	and you	should never subclass
       them.  Instead, subclass	the methods they call.

       is_debug
	   This	method calls "get_debug".

       is_info
       is_fatal
	   These methods return	true.

       info
       fatal
       debug
	   These methods redispatch to "log", "log_fatal", and "log_debug"
	   respectively.

SEE ALSO
       o   Log::Dispatch

       o   String::Flogger

AUTHOR
       Ricardo SIGNES <rjbs@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2014 by Ricardo SIGNES.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.1			  2014-11-30		  Log::Dispatchouli(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | LOGGER PREFIX | METHODS FOR SUBCLASSING | METHODS FOR TESTING | METHODS FOR PROXY LOGGERS | METHODS FOR API COMPATIBILITY | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Dispatchouli&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help