manpagez: man pages & more
man Log::Message(3)
Home | html | info | man
Log::Message(3pm)      Perl Programmers Reference Guide      Log::Message(3pm)


       Log::Message - A generic message storing mechanism;


           use Log::Message private => 0, config => '/our/cf_file';

           my $log = Log::Message->new(    private => 1,
                                           level   => 'log',
                                           config  => '/my/cf_file',

           $log->store('this is my first message');

           $log->store(    message => 'message #2',
                           tag     => 'MY_TAG',
                           level   => 'carp',
                           extra   => ['this is an argument to the handler'],

           my @last_five_items = $log->retrieve(5);

           my @items = $log->retrieve( tag     => qr/my_tag/i,
                                       message => qr/\d/,
                                       remove  => 1,

           my @items = $log->final( level => qr/carp/, amount => 2 );

           my $first_error = $log->first()

           # croak with the last error on the stack

           # empty the stack


       Log::Message is a generic message storage mechanism.  It allows you to
       store messages on a stack -- either shared or private -- and assign
       meta-data to it.  Some meta-data will automatically be added for you,
       like a timestamp and a stack trace, but some can be filled in by the
       user, like a tag by which to identify it or group it, and a level at
       which to handle the message (for example, log it, or die with it)

       Log::Message also provides a powerful way of searching through items by
       regexes on messages, tags and level.


       There are 4 modules of interest when dealing with the Log::Message::*

           Log::Message provides a few methods to manipulate the stack it
           keeps.  It has the option of keeping either a private or a public
           stack.  More on this below.

           These are individual message items, which are objects that contain
           the user message as well as the meta-data described above.  See the
           Log::Message::Item manpage to see how to extract this meta-data and
           how to work with the Item objects.  You should never need to create
           your own Item objects, but knowing about their methods and
           accessors is important if you want to write your own handlers. (See

           These are a collection of handlers that will be called for a level
           that is used on a Log::Message::Item object.  For example, if a
           message is logged with the 'carp' level, the 'carp' handler from
           Log::Message::Handlers will be called.  See the
           Log::Message::Handlers manpage for more explanation about how
           handlers work, which one are available and how to create your own.

           Per Log::Message object, there is a configuration required that
           will fill in defaults if the user did not specify arguments to
           override them (like for example what tag will be set if none was
           provided), Log::Message::Config handles the creation of these

           Configuration can be specified in 4 ways:

           o   As a configuration file when you "use Log::Message"

           o   As arguments when you "use Log::Message"

           o   As a configuration file when you create a new Log::Message
               object.  (The config will then only apply to that object if you
               marked it as private)

           o   As arguments when you create a new Log::Message object.

               You should never need to use the Log::Message::Config module
               yourself, as this is transparently done by Log::Message, but
               its manpage does provide an explanation of how you can create a
               config file.


       When using Log::Message, or creating a new Log::Message object, you can
       supply various options to alter its behaviour.  Of course, there are
       sensible defaults should you choose to omit these options.

       Below an explanation of all the options and how they work.

           The path to a configuration file to be read.  See the manpage of
           Log::Message::Config for the required format

           These options will be overridden by any explicit arguments passed.

           Whether to create, by default, private or shared objects.  If you
           choose to create shared objects, all Log::Message objects will use
           the same stack.

           This means that even though every module may make its own $log
           object they will still be sharing the same error stack on which
           they are putting errors and from which they are retrieving.

           This can be useful in big projects.

           If you choose to create a private object, then the stack will of
           course be private to this object, but it will still fall back to
           the shared config should no private config or overriding arguments
           be provided.

           Log::Message makes use of another module to validate its arguments,
           which is called Params::Check, which is a lightweight, yet powerful
           input checker and parser. (See the Params::Check manpage for

           The verbose setting will control whether this module will generate
           warnings if something improper is passed as input, or merely
           silently returns undef, at which point Log::Message will generate a

           It's best to just leave this at its default value, which is '1'

       tag The tag to add to messages if none was provided. If neither your
           config, nor any specific arguments supply a tag, then Log::Message
           will set it to 'NONE'

           Tags are useful for searching on or grouping by. For example, you
           could tag all the messages you want to go to the user as 'USER
           ERROR' and all those that are only debug information with 'DEBUG'.

           At the end of your program, you could then print all the ones
           tagged 'USER ERROR' to STDOUT, and those marked 'DEBUG' to a log

           "level" describes what action to take when a message is logged.
           Just like "tag", Log::Message will provide a default (which is
           'log') if neither your config file, nor any explicit arguments are
           given to override it.

           See the Log::Message::Handlers manpage to see what handlers are
           available by default and what they do, as well as to how to add
           your own handlers.

           This indicates whether or not to automatically remove the messages
           from the stack when you've retrieved them.  The default setting
           provided by Log::Message is '0': do not remove.

           This indicates whether messages should always be fetched in
           chronological order or not.  This simply means that you can choose
           whether, when retrieving items, the item most recently added should
           be returned first, or the one that had been added most long ago.

           The default is to return the newest ones first



       This creates a new Log::Message object; The parameters it takes are
       described in the "Options" section below and let it just be repeated
       that you can use these options like this:

           my $log = Log::Message->new( %options );

       as well as during "use" time, like this:

           use Log::Message option1 => value, option2 => value

       There are but 3 rules to keep in mind:

       o   Provided arguments take precedence over a configuration file.

       o   Arguments to new take precedence over options provided at "use"

       o   An object marked private will always have an empty stack to begin


       This will create a new Item object and store it on the stack.

       Possible arguments you can give to it are:

           This is the only argument that is required. If no other arguments
           are given, you may even leave off the "message" key. The argument
           will then automatically be assumed to be the message.

       tag The tag to add to this message. If not provided, Log::Message will
           look in your configuration for one.

           The level at which this message should be handled. If not provided,
           Log::Message will look in your configuration for one.

           This is an array ref with arguments passed to the handler for this
           message, when it is called from store();

           The handler will receive them as a normal list

       store() will return true upon success and undef upon failure, as well
       as issue a warning as to why it failed.


       This will retrieve all message items matching the criteria specified
       from the stack.

       Here are the criteria you can discriminate on:

       tag A regex to which the tag must adhere. For example "qr/\w/".

           A regex to which the level must adhere.

           A regex to which the message must adhere.

           Maximum amount of errors to return

           Return in chronological order, or not?

           Remove items from the stack upon retrieval?

       In scalar context it will return the first item matching your criteria
       and in list context, it will return all of them.

       If an error occurs while retrieving, a warning will be issued and undef
       will be returned.


       This is a shortcut for retrieving the first item(s) stored on the
       stack. It will default to only retrieving one if called with no
       arguments, and will always return results in chronological order.

       If you only supply one argument, it is assumed to be the amount you
       wish returned.

       Furthermore, it can take the same arguments as "retrieve" can.


       This is a shortcut for retrieving the last item(s) stored on the stack.
       It will default to only retrieving one if called with no arguments, and
       will always return results in reverse chronological order.

       If you only supply one argument, it is assumed to be the amount you
       wish returned.

       Furthermore, it can take the same arguments as "retrieve" can.


       This removes all items from the stack and returns them to the caller


       Log::Message::Item(3), Log::Message::Handlers(3), Log::Message::Config(3)


       This module by Jos Boumans <>.


       Thanks to Ann Barcomb for her suggestions.


       This module is copyright (c) 2002 Jos Boumans <>.  All
       rights reserved.

       This library is free software; you may redistribute and/or modify it
       under the same terms as Perl itself.

perl v5.10.0                      2007-12-18                 Log::Message(3pm)

Mac OS X 10.6 - Generated Thu Sep 17 20:12:41 CDT 2009
© 2000-2018
Individual documents may contain additional copyright information.