1Log::Message(3pm) Perl Programmers Reference Guide Log::Message(3pm)
2
6 Log::Message - A generic message storing mechanism;
7
9 use Log::Message private => 0, config => '/our/cf_file';
10 my $log = Log::Message->new( private => 1,
12 level => 'log',
13 config => '/my/cf_file',
14 );
15 $log->store('this is my first message');
17 $log->store( message => 'message #2',
19 tag => 'MY_TAG',
20 level => 'carp',
21 extra => ['this is an argument to the handler'],
22 );
23 my @last_five_items = $log->retrieve(5);
25 my @items = $log->retrieve( tag => qr/my_tag/i,
27 message => qr/\d/,
28 remove => 1,
29 );
30 my @items = $log->final( level => qr/carp/, amount => 2 );
32 my $first_error = $log->first()
34 # croak with the last error on the stack
36 $log->final->croak;
37 # empty the stack
39 $log->flush();
40
42 Log::Message is a generic message storage mechanism. It allows you to
43 store messages on a stack -- either shared or private -- and assign
44 meta-data to it. Some meta-data will automatically be added for you,
45 like a timestamp and a stack trace, but some can be filled in by the
46 user, like a tag by which to identify it or group it, and a level at
47 which to handle the message (for example, log it, or die with it)
48 Log::Message also provides a powerful way of searching through items by
50 regexes on messages, tags and level.
51
53 There are 4 modules of interest when dealing with the Log::Message::*
54 modules:
55 Log::Message
57 Log::Message provides a few methods to manipulate the stack it
58 keeps. It has the option of keeping either a private or a public
59 stack. More on this below.
60 Log::Message::Item
62 These are individual message items, which are objects that contain
63 the user message as well as the meta-data described above. See the
64 Log::Message::Item manpage to see how to extract this meta-data and
65 how to work with the Item objects. You should never need to create
66 your own Item objects, but knowing about their methods and
67 accessors is important if you want to write your own handlers. (See
68 below)
69 Log::Message::Handlers
71 These are a collection of handlers that will be called for a level
72 that is used on a Log::Message::Item object. For example, if a
73 message is logged with the 'carp' level, the 'carp' handler from
74 Log::Message::Handlers will be called. See the
75 Log::Message::Handlers manpage for more explanation about how
76 handlers work, which one are available and how to create your own.
77 Log::Message::Config
79 Per Log::Message object, there is a configuration required that
80 will fill in defaults if the user did not specify arguments to
81 override them (like for example what tag will be set if none was
82 provided), Log::Message::Config handles the creation of these
83 configurations.
84 Configuration can be specified in 4 ways:
86 · As a configuration file when you "use Log::Message"
88 · As arguments when you "use Log::Message"
90 · As a configuration file when you create a new Log::Message
92 object. (The config will then only apply to that object if you
93 marked it as private)
94 · As arguments when you create a new Log::Message object.
96 You should never need to use the Log::Message::Config module
98 yourself, as this is transparently done by Log::Message, but
99 its manpage does provide an explanation of how you can create a
100 config file.
101
103 When using Log::Message, or creating a new Log::Message object, you can
104 supply various options to alter its behaviour. Of course, there are
105 sensible defaults should you choose to omit these options.
106 Below an explanation of all the options and how they work.
108 config
110 The path to a configuration file to be read. See the manpage of
111 Log::Message::Config for the required format
112 These options will be overridden by any explicit arguments passed.
114 private
116 Whether to create, by default, private or shared objects. If you
117 choose to create shared objects, all Log::Message objects will use
118 the same stack.
119 This means that even though every module may make its own $log
121 object they will still be sharing the same error stack on which
122 they are putting errors and from which they are retrieving.
123 This can be useful in big projects.
125 If you choose to create a private object, then the stack will of
127 course be private to this object, but it will still fall back to
128 the shared config should no private config or overriding arguments
129 be provided.
130 verbose
132 Log::Message makes use of another module to validate its arguments,
133 which is called Params::Check, which is a lightweight, yet powerful
134 input checker and parser. (See the Params::Check manpage for
135 details).
136 The verbose setting will control whether this module will generate
138 warnings if something improper is passed as input, or merely
139 silently returns undef, at which point Log::Message will generate a
140 warning.
141 It's best to just leave this at its default value, which is '1'
143 tag The tag to add to messages if none was provided. If neither your
145 config, nor any specific arguments supply a tag, then Log::Message
146 will set it to 'NONE'
147 Tags are useful for searching on or grouping by. For example, you
149 could tag all the messages you want to go to the user as 'USER
150 ERROR' and all those that are only debug information with 'DEBUG'.
151 At the end of your program, you could then print all the ones
153 tagged 'USER ERROR' to STDOUT, and those marked 'DEBUG' to a log
154 file.
155 level
157 "level" describes what action to take when a message is logged.
158 Just like "tag", Log::Message will provide a default (which is
159 'log') if neither your config file, nor any explicit arguments are
160 given to override it.
161 See the Log::Message::Handlers manpage to see what handlers are
163 available by default and what they do, as well as to how to add
164 your own handlers.
165 remove
167 This indicates whether or not to automatically remove the messages
168 from the stack when you've retrieved them. The default setting
169 provided by Log::Message is '0': do not remove.
170 chrono
172 This indicates whether messages should always be fetched in
173 chronological order or not. This simply means that you can choose
174 whether, when retrieving items, the item most recently added should
175 be returned first, or the one that had been added most long ago.
176 The default is to return the newest ones first
178
180 new
181 This creates a new Log::Message object; The parameters it takes are
182 described in the "Options" section below and let it just be repeated
183 that you can use these options like this:
184 my $log = Log::Message->new( %options );
186 as well as during "use" time, like this:
188 use Log::Message option1 => value, option2 => value
190 There are but 3 rules to keep in mind:
192 · Provided arguments take precedence over a configuration file.
194 · Arguments to new take precedence over options provided at "use"
196 time
197 · An object marked private will always have an empty stack to begin
199 with
200 store
202 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
229 from the stack.
230 Here are the criteria you can discriminate on:
232 tag A regex to which the tag must adhere. For example "qr/\w/".
234 level
236 A regex to which the level must adhere.
237 message
239 A regex to which the message must adhere.
240 amount
242 Maximum amount of errors to return
243 chrono
245 Return in chronological order, or not?
246 remove
248 Remove items from the stack upon retrieval?
249 In scalar context it will return the first item matching your criteria
251 and in list context, it will return all of them.
252 If an error occurs while retrieving, a warning will be issued and undef
254 will be returned.
255 first
257 This is a shortcut for retrieving the first item(s) stored on the
258 stack. It will default to only retrieving one if called with no
259 arguments, and will always return results in chronological order.
260 If you only supply one argument, it is assumed to be the amount you
262 wish returned.
263 Furthermore, it can take the same arguments as "retrieve" can.
265 last
267 This is a shortcut for retrieving the last item(s) stored on the stack.
268 It will default to only retrieving one if called with no arguments, and
269 will always return results in reverse chronological order.
270 If you only supply one argument, it is assumed to be the amount you
272 wish returned.
273 Furthermore, it can take the same arguments as "retrieve" can.
275 flush
277 This removes all items from the stack and returns them to the caller
278
280 Log::Message::Item, Log::Message::Handlers, Log::Message::Config
281
283 This module by Jos Boumans <kane@cpan.org>.
284
286 Thanks to Ann Barcomb for her suggestions.
287
289 This module is copyright (c) 2002 Jos Boumans <kane@cpan.org>. All
290 rights reserved.
291 This library is free software; you may redistribute and/or modify it
293 under the same terms as Perl itself.
294perl v5.12.4 2011-06-07 Log::Message(3pm)