1Log::Message(3) User Contributed Perl Documentation Log::Message(3)
2
6 Log::Message;
7
9 my $log = Log::Message->new( private => 1,
10 level => 'log',
11 config => '/my/cf_file',
12 );
13 $log->store('this is my first message');
15 $log->store( message => 'message #2',
17 tag => 'MY_TAG',
18 level => 'carp',
19 extra => ['this is an argument to the handler'],
20 );
21 my @last_five_items = $log->retrieve(5);
23 my @items = $log->retrieve( tag => qr/my_tag/i,
25 message => qr/\d/,
26 remove => 1,
27 );
28 my @items = $log->final( level => qr/carp/, amount => 2 );
30 my $first_error = $log->first()
32 # croak with the last error on the stack
34 $log->final->croak;
35 # empty the stack
37 $log->flush();
38
40 Log::Message is a generic message storage mechanism. It allows you to
41 store messages on a stack -- either shared or private -- and assign
42 meta-data to it. Some meta-data will automatically be added for you,
43 like a timestamp and a stack trace, but some can be filled in by the
44 user, like a tag by which to identify it or group it, and a level at
45 which to handle the message (for example, log it, or die with it)
46 Log::Message also provides a powerfull way of searching through items
48 by regexes on messages, tags and level.
49
51 There are 4 modules of interest when dealing with the Log::Message::*
52 modules:
53 Log::Message
55 Log::Message provides a few methods to manipulate the stack it
56 keeps. It has the option of keeping either a private or a public
57 stack. More on this below.
58 Log::Message::Item
60 These are individual message items, which are objects that contain
61 the user message as well as the meta-data described above. See the
62 Log::Message::Item manpage to see how to extract this meta-data and
63 how to work with the Item objects. You should never need to create
64 your own Item objects, but knowing about their methods and acces‐
65 sors is important if you want to write your own handlers. (See
66 below)
67 Log::Message::Handlers
69 These are a collection of handlers that will be called for a level
70 that is used on a Log::Message::Item object. For example, if a
71 message is logged with the 'carp' level, the 'carp' handler from
72 Log::Message::Handlers will be called. See the Log::Message::Han‐
73 dlers manpage for more explenation about how handlers work, which
74 one are available and how to create your own.
75 Log::Message::Config
77 Per Log::Message object, there is a configuration required that
78 will fill in defaults if the user did not specify arguments to
79 override them (like for example what tag will be set if none was
80 provided), Log::Message::Config handles the creation of these con‐
81 figurations.
82 Configuration can be specified in 4 ways:
84 * As a configuration file when you "use Log::Message"
86 * As arguments when you "use Log::Message"
88 * As a configuration file when you create a new Log::Message
90 object. (The config will then only apply to that object if you
91 marked it as private)
92 * As arguments when you create a new Log::Message object.
94 You should never need to use the Log::Message::Config module
96 yourself, as this is transparently done by Log::Message, but
97 it's manpage does provide an explenation of how you can create
98 a config file.
99
101 When using Log::Message, or creating a new Log::Message object, you can
102 supply various options to alter it's behaviour. Of course, there are
103 sensible defaults should you choose to omit these options.
104 Below an explenation of all the options and how they work.
106 config
108 The path to a configuration file to be read. See the manpage of
109 Log::Message::Config for the required format
110 These options will be overridden by any explicit arguments passed.
112 private
114 Wether to create, by default, private or shared objects. If you
115 choose to create shared objects, all Log::Message objects will use
116 the same stack.
117 This means that even though every module may make it's own $log
119 object they will still be sharing the same error stack on which
120 they are putting errors and from which they are retrieving.
121 This can be usefull in big projects.
123 If you choose to create a private object, then the stack will of
125 course be private to this object, but it will still fall back to
126 the shared config should no private config or overriding arguments
127 be provided.
128 verbose
130 Log::Message makes use of another module to validate it's argu‐
131 ments, which is called Params::Check, which is a lightweight, yet
132 powerful input checker and parser. (See the Params::Check manpage
133 for details).
134 The verbose setting will control whether this module will generate
136 warnings if something improper is passed as input, or merely
137 silently returns undef, at which point Log::Message will generate a
138 warning.
139 It's best to just leave this at it's default value, which is '1'
141 tag The tag to add to messages if none was provided. If neither your
143 config, nor any specific arguments supply a tag, then Log::Message
144 will set it to 'NONE'
145 Tags are usefull for searching on or grouping by. For example, you
147 could tag all the messages you want to go to the user as 'USER
148 ERROR' and all those that are only debug information with 'DEBUG'.
149 At the end of your program, you could then print all the ones
151 tagged 'USER ERROR' to STDOUT, and those marked 'DEBUG' to a log
152 file.
153 level
155 "level" describes what action to take when a message is logged.
156 Just like "tag", Log::Message will provide a default (which is
157 'log') if neither your config file, nor any explicit arguments are
158 given to override it.
159 See the Log::Message::Handlers manpage to see what handlers are
161 available by default and what they do, as well as to how to add
162 your own handlers.
163 remove
165 This indicates whether or not to automatically remove the messages
166 from the stack when you've retrieved them. The default setting
167 provided by Log::Message is '0': do not remove.
168 chrono
170 This indicates whether messages should always be fetched in chrono‐
171 logical order or not. This simply means that you can choose
172 whether, when retrieving items, the item most recently added should
173 be returned first, or the one that had been added most long ago.
174 The default is to return the newest ones first
176
178 new
179 This creates a new Log::Message object; The parameters it takes are
181 described in the "Options" section below and let it just be repeated
182 that you can use these options like this:
183 my $log = Log::Message->new( %options );
185 as well as during "use" time, like this:
187 use Log::Message option1 => value, option2 => value
189 There are but 3 rules to keep in mind:
191 · Provided arguments take precedence over a configuration file.
193 · Arguments to new take precedence over options provided at "use"
195 time
196 · An object marked private will always have an empty stack to begin
198 with
199 store
201 This will create a new Item object and store it on the stack.
203 Possible arguments you can give to it are:
205 message
207 This is the only argument that is required. If no other arguments
208 are given, you may even leave off the "message" key. The argument
209 will then automatically be assumed to be the message.
210 tag The tag to add to this message. If not provided, Log::Message will
212 look in your configuration for one.
213 level
215 The level at which this message should be handled. If not provided,
216 Log::Message will look in your configuration for one.
217 extra
219 This is an array ref with arguments passed to the handler for this
220 message, when it is called from store();
221 The handler will receive them as a normal list
223 store() will return true upon success and undef upon failure, as well
225 as issue a warning as to why it failed.
226 retrieve
228 This will retrieve all message items matching the criteria specified
230 from the stack.
231 Here are the criteria you can discriminate on:
233 tag A regex to which the tag must adhere. For example "qr/\w/".
235 level
237 A regex to which the level must adhere.
238 message
240 A regex to which the message must adhere.
241 amount
243 Maximum amount of errors to return
244 chrono
246 Return in chronological order, or not?
247 remove
249 Remove items from the stack upon retrieval?
250 In scalar context it will return the first item matching your criteria
252 and in list context, it will return all of them.
253 If an error occurs while retrieving, a warning will be issued and undef
255 will be returned.
256 first
258 This is a shortcut for retrieving the first item(s) stored on the
260 stack. It will default to only retrieving one if called with no argu‐
261 ments, and will always return results in chronological order.
262 If you only supply one argument, it is assumed to be the amount you
264 wish returned.
265 Furthermore, it can take the same arguments as "retrieve" can.
267 first
269 This is a shortcut for retrieving the last item(s) stored on the stack.
271 It will default to only retrieving one if called with no arguments, and
272 will always return results in reverse chronological order.
273 If you only supply one argument, it is assumed to be the amount you
275 wish returned.
276 Furthermore, it can take the same arguments as "retrieve" can.
278 flush
280 This removes all items from the stack and returns them to the caller
282
284 Log::Message::Item, Log::Message::Handlers, Log::Message::Config
285
287 This module by Jos Boumans <kane@cpan.org>.
288
290 Thanks to Ann Barcomb for her suggestions.
291
293 This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>. All
294 rights reserved.
295 This library is free software; you may redistribute and/or modify it
297 under the same terms as Perl itself.
298perl v5.8.8 2003-05-07 Log::Message(3)