Bio::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

start_color()
    Changes color of output stream to that of specified logging level. This so that for example all errors are automatically marked up as 'FATAL', or all output generated by an external program is marked up as 'DEBUG'

     Type    : Mutator
     Title   : start_color()
     Usage   : $logger->start_color( 'DEBUG', \*STDOUT )
     Function: Changes color of output stream
     Returns : color name
     Args    : Log level whose color to use,
               (optional) which stream to change, default is STDERR

stop_color()
    Resets the color initiated by start_color()

     Type    : Mutator
     Title   : stop_color()
     Usage   : $logger->stop_color( \*STDOUT )
     Function: Changes color of output stream
     Returns : color name
     Args    : (Optional) which stream to reset, default is STDERR

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>