1Log::Message(3)       User Contributed Perl Documentation      Log::Message(3)
2
3
4

NAME

6       Log::Message - A generic message storing mechanism;
7

SYNOPSIS

9           use Log::Message private => 0, config => '/our/cf_file';
10
11           my $log = Log::Message->new(    private => 1,
12                                           level   => 'log',
13                                           config  => '/my/cf_file',
14                                      );
15
16           $log->store('this is my first message');
17
18           $log->store(    message => 'message #2',
19                           tag     => 'MY_TAG',
20                           level   => 'carp',
21                           extra   => ['this is an argument to the handler'],
22                      );
23
24           my @last_five_items = $log->retrieve(5);
25
26           my @items = $log->retrieve( tag     => qr/my_tag/i,
27                                       message => qr/\d/,
28                                       remove  => 1,
29                                     );
30
31           my @items = $log->final( level => qr/carp/, amount => 2 );
32
33           my $first_error = $log->first()
34
35           # croak with the last error on the stack
36           $log->final->croak;
37
38           # empty the stack
39           $log->flush();
40

DESCRIPTION

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
49       Log::Message also provides a powerful way of searching through items by
50       regexes on messages, tags and level.
51

Hierarchy

53       There are 4 modules of interest when dealing with the Log::Message::*
54       modules:
55
56       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
61       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
70       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
78       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
85           Configuration can be specified in 4 ways:
86
87           •   As a configuration file when you "use Log::Message"
88
89           •   As arguments when you "use Log::Message"
90
91           •   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
95           •   As arguments when you create a new Log::Message object.
96
97               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

Options

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
107       Below an explanation of all the options and how they work.
108
109       config
110           The path to a configuration file to be read.  See the manpage of
111           Log::Message::Config for the required format
112
113           These options will be overridden by any explicit arguments passed.
114
115       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
120           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
124           This can be useful in big projects.
125
126           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
131       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
137           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
142           It's best to just leave this at its default value, which is '1'
143
144       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
148           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
152           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
156       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
162           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
166       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
171       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
177           The default is to return the newest ones first
178

Methods

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
185           my $log = Log::Message->new( %options );
186
187       as well as during "use" time, like this:
188
189           use Log::Message option1 => value, option2 => value
190
191       There are but 3 rules to keep in mind:
192
193       •   Provided arguments take precedence over a configuration file.
194
195       •   Arguments to new take precedence over options provided at "use"
196           time
197
198       •   An object marked private will always have an empty stack to begin
199           with
200
201   store
202       This will create a new Item object and store it on the stack.
203
204       Possible arguments you can give to it are:
205
206       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
211       tag The tag to add to this message. If not provided, Log::Message will
212           look in your configuration for one.
213
214       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
218       extra
219           This is an array ref with arguments passed to the handler for this
220           message, when it is called from store();
221
222           The handler will receive them as a normal list
223
224       store() will return true upon success and undef upon failure, as well
225       as issue a warning as to why it failed.
226
227   retrieve
228       This will retrieve all message items matching the criteria specified
229       from the stack.
230
231       Here are the criteria you can discriminate on:
232
233       tag A regex to which the tag must adhere. For example "qr/\w/".
234
235       level
236           A regex to which the level must adhere.
237
238       message
239           A regex to which the message must adhere.
240
241       amount
242           Maximum amount of errors to return
243
244       chrono
245           Return in chronological order, or not?
246
247       remove
248           Remove items from the stack upon retrieval?
249
250       In scalar context it will return the first item matching your criteria
251       and in list context, it will return all of them.
252
253       If an error occurs while retrieving, a warning will be issued and undef
254       will be returned.
255
256   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
261       If you only supply one argument, it is assumed to be the amount you
262       wish returned.
263
264       Furthermore, it can take the same arguments as "retrieve" can.
265
266   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
271       If you only supply one argument, it is assumed to be the amount you
272       wish returned.
273
274       Furthermore, it can take the same arguments as "retrieve" can.
275
276   flush
277       This removes all items from the stack and returns them to the caller
278

SEE ALSO

280       Log::Message::Item, Log::Message::Handlers, Log::Message::Config
281

AUTHOR

283       This module by Jos Boumans <kane@cpan.org>.
284

Acknowledgements

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
292       This library is free software; you may redistribute and/or modify it
293       under the same terms as Perl itself.
294
295
296
297perl v5.36.0                      2023-01-20                   Log::Message(3)
Impressum