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

FreeBSD Manual Pages

  
 
  

home | help
Bio::Phylo::Util::LoggUser)Contributed Perl DocumenBio::Phylo::Util::Logger(3)

NAME
       Bio::Phylo::Util::Logger	- Logger of internal messages of several
       severity	levels

SYNOPSIS
	use strict;
	use Bio::Phylo::Util::Logger ':levels';	# import level constants
	use Bio::Phylo::IO 'parse';
	use Bio::Phylo::Factory;

	# Set the verbosity level of the tree class.
	# "DEBUG" is the most verbose level. All log messages
	# emanating from the tree class	will be
	# transmitted. For this	to work	the level constants
	# have to have been imported!
	use Bio::Phylo::Forest::Tree 'verbose' => DEBUG; # note: DEBUG is not quoted!

	# Create a file	handle for logger to write to.
	# This is not necessary, by default the	logger
	# writes to STDERR, but	sometimes you will want
	# to write to a	file, as per this example.
	open my	$fh, '>', 'parsing.log'	or die $!;

	# Create a logger object.
	my $fac	= Bio::Phylo::Factory->new;
	my $logger = $fac->create_logger;

	# Set the verbosity level of the set_name
	# method in the	base class. Messages coming
	# from this method will	be transmitted.
	$logger->VERBOSE(
	    '-level'  => DEBUG,	# note,	not quoted, this is a constant!
	    '-method' => 'Bio::Phylo::set_name', # quoted, otherwise bareword error!
	);

	# 'Listeners' are subroutine references	that
	# are executed when a message is transmitted.
	# The first argument passed to these subroutines
	# is the log message. This particular listener
	# will write the message to the	'parsing.log'
	# file,	if the $fh file	handle is still	open.
	$logger->set_listeners(
	    sub	{
		my ($msg) = @_;
		if ( $fh->opened ) {
		    print $fh $msg;
		}
	    }
	);

	# Now parse a tree, and	see what is logged.
	my $tree = parse(
	    '-format' => 'newick',
	    '-string' => do { local $/;	<DATA> },
	)->first;

	# Cleanly close	the log	handle.
	close $fh;

	__DATA__
	((((A,B),C),D),E);

       The example above will write something like the following to the	log
       file:

	INFO Bio::Phylo::Forest::Tree::new [Bio/Phylo/Forest/Tree.pm, 99] - constructor	called for 'Bio::Phylo::Forest::Tree'
	INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] -	setting	name 'A'
	INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] -	setting	name 'B'
	INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] -	setting	name 'C'
	INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] -	setting	name 'D'
	INFO Bio::Phylo::set_name [Bio/Phylo.pm, 281] -	setting	name 'E'

DESCRIPTION
       This class defines a logger, a utility object for logging messages.
       The other objects in Bio::Phylo use this	logger to give detailed
       feedback	about what they	are doing at per-class,	per-method, user-
       configurable log	levels (DEBUG, INFO, WARN, ERROR and FATAL). These log
       levels are constants that are optionally	exported by this class by
       passing the ':levels' argument to your 'use' statement, like so:

	use Bio::Phylo::Util::Logger ':levels';

       If for some reason you don't want this behaviour	(i.e. because there is
       something else by these same names in your namespace) you must use the
       fully qualified names for these levels, i.e.
       Bio::Phylo::Util::Logger::DEBUG and so on.

       The least verbose is level FATAL, in which case only 'fatal' messages
       are shown.  The most verbose level, DEBUG, shows	debugging messages,
       including from internal methods (i.e. ones that start with underscores,
       and special 'ALLCAPS' perl methods like DESTROY or TIEARRAY). For
       example,	to monitor what	the root class is doing, you would say:

	$logger->( -class => 'Bio::Phylo', -level => DEBUG )

       To define global	verbosity you can omit the -class argument. To set
       verbosity at a more granular level, you can use the -method argument,
       which takes a fully qualified method name such as
       'Bio::Phylo::set_name', such that messages originating from within that
       method's	body get a different verbosity level.

METHODS
   CONSTRUCTOR
       new()
	   Constructor for Logger.

	    Type    : Constructor
	    Title   : new
	    Usage   : my $logger = Bio::Phylo::Util::Logger->new;
	    Function: Instantiates a logger
	    Returns : a	Bio::Phylo::Util::Logger object
	    Args    : -level  => Bio::Phylo::Util::Logger::INFO	(DEBUG/INFO/WARN/ERROR/FATAL)
		      -class  => a package (or array ref) for which to set verbosity (optional)
		      -method => a sub name (or	array ref) for which to	set verbosity (optional)
		      -file   => a file	to which to append logging messages
		      -listeners => array ref of subs that handle logging messages
		      -prefix	 => a path fragment to strip from the paths in logging messages

   VERBOSITY LEVELS
       FATAL
	   Rarely happens, usually an exception	is thrown instead.

       ERROR
	   If this happens, something is seriously wrong that needs to be
	   addressed.

       WARN
	   If this happens, something is seriously wrong that needs to be
	   addressed.

       INFO
	   If something	weird is happening, turn up verbosity to this level as
	   it might explain some of the	assumptions the	code is	making.

       DEBUG
	   This	is very	verbose, probably only useful if you write core
	   Bio::Phylo code.

   LOGGING METHODS
       debug()
	   Prints argument debugging message, depending	on verbosity.

	    Type    : logging method
	    Title   : debug
	    Usage   : $logger->debug( "debugging message" );
	    Function: prints debugging message,	depending on verbosity
	    Returns : invocant
	    Args    : logging message

       info()
	   Prints argument informational message, depending on verbosity.

	    Type    : logging method
	    Title   : info
	    Usage   : $logger->info( "info message" );
	    Function: prints info message, depending on	verbosity
	    Returns : invocant
	    Args    : logging message

       warn()
	   Prints argument warning message, depending on verbosity.

	    Type    : logging method
	    Title   : warn
	    Usage   : $logger->warn( "warning message" );
	    Function: prints warning message, depending	on verbosity
	    Returns : invocant
	    Args    : logging message

       error()
	   Prints argument error message, depending on verbosity.

	    Type    : logging method
	    Title   : error
	    Usage   : $logger->error( "error message" );
	    Function: prints error message, depending on verbosity
	    Returns : invocant
	    Args    : logging message

       fatal()
	   Prints argument fatal message, depending on verbosity.

	    Type    : logging method
	    Title   : fatal
	    Usage   : $logger->fatal( "fatal message" );
	    Function: prints fatal message, depending on verbosity
	    Returns : invocant
	    Args    : logging message

       set_listeners()
	   Adds	listeners to send log messages to.

	    Type    : Mutator
	    Title   : set_listeners()
	    Usage   : $logger->set_listeners( sub { warn shift } )
	    Function: Sets additional listeners	to log to (e.g.	a file)
	    Returns : invocant
	    Args    : One or more code references
	    Comments: On execution of the listeners, the @_ arguments are:
		      $log_string, # the formatted log string
		      $level,	   # log level,	i.e DEBUG, INFO, WARN, ERROR or	FATAL
		      $subroutine, # the calling subroutine
		      $filename,   # filename where log	method was called
		      $line,	   # line where	log method was called
		      $msg	   # the unformatted message

       PREFIX()
	   Getter and setter of	path prefix to strip from source file paths in
	   messages.  By default, messages will	have a field such as
	   "[$PREFIX/Bio/Phylo.pm, 280]", which	indicates the message was sent
	   from	line 280 in file Bio/Phylo.pm inside path $PREFIX. This	is
	   done	so that	your log won't be cluttered with unnecessarily long
	   paths. To find out what $PREFIX is set to, call the PREFIX()	method
	   on the logger, and to change	it provide a path argument relative to
	   which the paths to source files will	be constructed.

	    Type    : Mutator/Accessor
	    Title   : PREFIX()
	    Usage   : $logger->PREFIX( '/path/to/bio/phylo' )
	    Function: Sets/gets	$PREFIX
	    Returns : Verbose level
	    Args    : Optional:	a path
	    Comments:

       VERBOSE()
	   Setter for the verbose level. This comes in five levels:

	       FATAL = only fatal messages (though, when something fatal happens, you'll most
	       likely get an exception object),

	       ERROR = errors (hopefully recoverable),

	       WARN = warnings (recoverable),

	       INFO = info (useful diagnostics),

	       DEBUG = debug (almost every method call)

	   Without additional arguments, i.e. by just calling VERBOSE( -level
	   => $level ),	you set	the global verbosity level. By default this is
	   2. By increasing this level,	the number of messages quickly becomes
	   too great to	make sense out of.  To focus on	a particular class,
	   you can add the -class => 'Some::Class' (where 'Some::Class'	stands
	   for any of the class	names in the Bio::Phylo	release) argument,
	   which means that messages originating from that class will have a
	   different (presumably higher) verbosity level than the global
	   level.  By adding the -method => 'Fully::Qualified::method_name'
	   (say, 'Bio::Phylo::set_name'), you can change the verbosity of a
	   specific method. When evaluating whether or not to transmit a
	   message, the	method-specific	verbosity level	takes precedence over
	   the class-specific level, which takes precedence over the global
	   level.

	    Type    : Mutator
	    Title   : VERBOSE()
	    Usage   : $logger->VERBOSE(	-level => $level )
	    Function: Sets/gets	verbose	level
	    Returns : Verbose level
	    Args    : -level   => 4 # or lower

		      #	optional, or any other class
		      -class   => 'Bio::Phylo'

		      #	optional, fully	qualified method name
		      -method' => 'Bio::Phylo::set_name'

SEE ALSO
       There is	a mailing list at
       <https://groups.google.com/forum/#!forum/bio-phylo> for any user	or
       developer questions and discussions.

       Also see	the manual: Bio::Phylo::Manual and
       <http://rutgervos.blogspot.com>.

CITATION
       If you use Bio::Phylo in	published research, please cite	it:

       Rutger A	Vos, Jason Caravas, Klaas Hartmann, Mark A Jensen and Chase
       Miller, 2011. Bio::Phylo	- phyloinformatic analysis using Perl.	BMC
       Bioinformatics 12:63.  <http://dx.doi.org/10.1186/1471-2105-12-63>

perl v5.24.1			  2014-02-08	   Bio::Phylo::Util::Logger(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | CITATION

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

home | help