|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<BODY bgcolor="FFFFFF">
<title>
CMS MessageLogger: Configuring the MessageLogger Service
</title>
<center>
<h1> <img src="header-public.gif" align="center"> </h1>
<font color=red>
<h1>CMS MessageLogger Service
<br>
Configuring the MessageLogger Service</h1>
</font>
</center>
<p>
The <a href="MessageLogger.html">CMS MessageLogger Service </a>
is meant to allow code to log
messages to a unified message logging
and statistics facility.
While reasonable default behaviors are provided,
the behavior of the MessageLogger can be adjusted via lines in the
job's configuration file (.cfg).
<p>
<ul>
<li> <a href="#Concepts"> Message Logging Concepts </a>
<li> <a href="#cms"> Routine MessageLogger Parameters </a>
<li> <a href="#example"> Example .cfg File Exercising Some Options</a>
<li> <a href="#log4cplus"> Routing Messages to log4cplus </a>
<li> <a href="#debug"> Enable LogDebug Messages </a>
<li> <a href="#complete"> Examples of Limits and Timespan Parameters </a>
<li> <a href="#linelength"> Adjusting Linebreak Policy </a>
<li> <a href="statistics.html"> Obtaining Message Statistics </a>
</ul>
<p>
<a name="concepts">
<h2> Message Logging Concepts </h2>
To understand what sort of flexibility is available, it is useful to
be familiar with the following concepts:
<ul>
<li><font color=blue><b> Destination
</b></font>
<ul>
The MessageLogger is capable of routing messages to multiple
<b>Destination</b>s.
The behavior -- the nature of which messages would appear
and which would be ignored -- can be controlled for each destination.
At present, two types of <b>destination</b>s are supported:
<ol>
<li> Output files, the names of which can be specified in the job's
.cfg file. (If the file specified already exists, the messages will
be appended to the file.)
<li> Streams <font color=blue><b>cerr</b></font> and
<font color=blue><b>cout</b></font>. (Because our parameter set
syntax treats these names specially, creation of an output <em>file</em>
named cerr or cout is not supported.)
</ol>
</ul>
<li><font color=blue><b> Message ID
</b></font>
<ul>
Each message is given a category when issued. This is intended to represent
what this message is about. For example, several messages
with different detailed content could all be of type <b>tracking</b>.
Limits can be imposed on the reporting of messages in a given category,
and statistics can be obtained by category.
</ul>
<li><font color=blue><b> Severity
</b></font>
<ul>
<font color=blue>LogDebug</font>,
<font color=blue>edm::LogWarning</font>,
<font color=blue>edm::LogInfo</font>, and
<font color=blue>edm::LogError</font> produce messages with severity
<font color=blue>DEBUG</font>,
<font color=blue>WARNING</font>,
<font color=blue>INFO</font>, and
<font color=blue>ERROR</font> respectively.
These are ordered with <font color=blue>DEBUG</font> as the lowest
severity and <font color=blue>ERROR</font> as the highest.
</ul>
<li><font color=blue><b> Threshold
</b></font>
<ul>
For any given destination, the .cfg file can specify that every
message with a severity lower than a given <font color=blue>threshold</font>
shall be ignored.
<font color=green>By default, a destination will have a threshold of
<font color=blue>INFO</font>; responses to messages issued via LogDebug
can be enabled by setting a threshold to <font color=blue>DEBUG</font>.
</font>
</ul>
<li><font color=blue><b> Limit
</b></font>
<ul>
For each message category,
or for messages in general, or for a specified severity
level, the .cfg file can instruct the logger to ignore messages after some
number (the <font color=blue>limit</font>) have been encountered.
(Actually, beyond the applicable limit, an occasional further message will
appear, based on an exponential backoff. Thus, if the a limit is set at
5, and 100 messages of that id are issued, then that destination will react
to the messages number 1, 2, 3, 4, 5, 10, 15, 25, 45, and 85.) A limit of
zero will disable reporting that category of messages.
</ul>
<li><font color=blue><b> Timespan
</b></font>
<ul>
When a limit is set, it is possible to specify that if no occurrences of that
type of message are seen in some number of seconds (the
<font color=blue>timespan</font>), then the count toward that limit is to
be reset. Thus if you wish to suppress most of the thousands of warnings of
some type expected at startup, but would like to know if another one happens
after a gap of ten minutes, this can be specified as a timespan of 600.
</ul>
</ul>
<p>
The typical user may not be interested in specifying limits of how many times
messages of types will be displayed.
<font color=green> By default, the MessageLogger service
will impose a limit of 5 occurrences of each category of
LogInfo messages, except for framework event messages which will be
unlimited. </font>
output to each destination every messages meeting the severity threshold
criteria specific for that destination. In fact, the user need not specify
any thresholds; then every message will be output. And if the user does not
specify any destinations, then a single destination of cerr is assumed.
<p>
In the near future, concepts for establishing and/or controlling a destination
involving the <font color=blue> log4cplus </font> service may also
be listed here.
<a name="cms">
<h2> Routine MessageLogger Parameters </h2>
The following is a portion of a .cfg file requesting the MessageLogger
Service, and setting up setting a destination which will write messages
to the file <font color=blue>messages.txt</font>. The default threshold
and limits will apply: No LogDebug messages will be reported, and
only the first five messages of each category will be reported.
<font color=blue>
<pre>
process TEST =
{
service = MessageLoggger { vstring destinations = { "messages.txt" } }
}
</pre>
</font>
<a name="example">
<h2> Example .cfg File Exercising Some Options </h2>
The following is an example .cfg file, requesting the MessageLogger
Service, setting up some destinations, and specifying some thresholds
for how "severe" a message must be in order for it to appear in each
destination.
<pre>
process TEST = {
<a href="serviceML.html">service = MessageLogger</a> {
<a href="files.html">vstring destinations = </a>{ <a href="filename.html">"detailedInfo.txt"</a>
, <a href="filename.html">"critical.txt"</a>
, <a href="cout.html">"cout"</a>
, <a href="cerr.html">"cerr"</a>
}
<a href="filename.html">PSet critical.txt</a> = { <a href="errorthreshold.html">string threshold = "ERROR"</a> }
<a href="filename.html">PSet detailedInfo.txt</a> = { <a href="infothreshold.html">string threshold = "INFO"</a> }
<a href="cerr.html">PSet cerr</a> = { <a href="warnthreshold.html">string threshold = "WARNING"</a> }
}
untracked PSet maxEvents = {untracked int32 input = 5}
path p = { myAnalysisModule }
module myAnalysisModule = ModuleThatIssuesMessages { }
source = EmptySource { }
}
</pre>
<a name="debug">
<h2> Enabling LogDebug Messages </h2>
The following is a portion of a .cfg file appropriate for a job that will
run code instrumented with many LogDebug messages. This hypothetical user
cares only about those LogDebug messages in the category
<font color=blue>interestingToMe</font> and, in this file, prefers not
to see any other LogDebug or LogInfo messages.
<font color=blue>
<pre>
process TEST =
{
service = MessageLoggger
{
vstring destinations = { "debugmessages.txt" }
vstring categories = { "interestingToMe" }
vstring debugModules = { "*" }
PSet debugmessages.txt = { string threshold = "DEBUG"
PSet INFO = { int32 limit = 0 }
PSet DEBUG = { int32 limit = 0 }
PSet interestingToMe = {int32 limit = 10000000}
}
}
</pre>
</font>
By default, all LogDebug messages issued from any modules would be
rapidly discarded. This user chooses to enable the LogDebug messages
issued by all modules, via
<font color=blue>vstring debugModules = { "*" }</font>. (Instead,
LogDebugs from a set of specific modules could be enabled; see
<a href="debug.html#enabling">
Controlling LogDebug Behavior: Enabling LogDebug Messages </a> for details.
<p>
Even if LogDebug messages are not rapidly discarded, destination have
a default threshold of <code>INFO</code>, so no LogDebug messages would be
reported.
Here, for the <code>debugmessages.txt</code> destination,
the user causes LogDebug messages to be reported by
<font color=blue>string threshold = "DEBUG"</font>.
If the PSet for <code>debugmessages.txt</code> were to end there,
all LogDebug messages would be reported by this destination.
<p>
This user, however, desires more selectivity.
The next two lines establish that for any category of messages
without its own limit specification, if the message has severity
INFO or DEBUG, use a limit of zero (which means don't report those
messages). Finally, the .cfg file overrides this for messages in the
category <font color=blue>interestingToMe</font>, permitting messages of
that category to be reported.
<a name="log4cplus">
<h2> Routing Messages to log4cplus </h2>
The MessageLogger will route messages to <b><code>log4cplus</code></b>
if the .cfg file requests the <b><code>MLlog4cplus</code></b> service.
The following is an example .cfg file, requesting the
<code>MLlog4cplus</code>
service, and specifying a threshold
for how "severe" a message must be in order for it to be routed to
<code>log4cplus</code>.
<pre>
process TEST = {
<a href="log4cplus.html">service = MLlog4cplus</a>
service = MessageLogger {
vstring destinations = { "detailedInfo.txt" }
<a href="log4cplus.html">PSet log4cplus = { string threshold = "ERROR" }</a>
}
untracked PSet maxEvents = {untracked int32 input = 5}
path p = { myAnalysisModule }
module myAnalysisModule = ModuleThatIssuesMessages { }
source = EmptySource { }
}
</pre>
The four severities of MessageLogger messages correspond to the four
directives for issuing to <code>log4cplus</code>. For instance,
<code>LogWarning("category")</code> leads to a <code>LOG4CPLUS_WARN(...)</code>
call.
<p>
<code>log4cplus</code> dispatches to "appenders". For example, a
<code>fileAppender</code> may be established to write the text to
a file, or a <code>consoleAppender</code> to write to the job console.
It is up to the user code or configuration file to establish which
appenders are wanted.
In the current implementation,
the <code>MLlog4cplus</code> service automatically
establishes a <code>fileAppender</code> writing <code>log4cplus.ouput</code>.
<a name="complete">
<h2> Examples of Limits and Timespan Parameters </h2>
The following is an example .cfg file, requesting the MessageLogger
Service, setting up some destinations, and specifying some
choices for thresholds, and for limits and timespans applicable
to severities, to specific
message ID's, and to all non-specified (default) message ID's.
<p>
The .cfg file contains not only a list of files, but also a list of message
ID's that the author wishes to control individually.
<pre>
process TEST = {
<a href="serviceMLc.html">service = MessageLogger {</a>
<a href="destinations.html">vstring destinations = { "detailedInfo.txt"</a>
<a href="destinations.html">, "critical.txt"</a>
<a href="destinations.html">, "jobdebug.txt"</a>
<a href="destinations.html">, "anotherfile.txt"</a>
<a href="destinations.html">, "cout"</a>
<a href="destinations.html">, "cerr"</a>
<a href="destinations.html">}</a>
<a href="mIDs.html">vstring categories = { "unimportant"</a>
<a href="mIDs.html">, "trkwarning"</a>
<a href="mIDs.html">, "serious_matter"</a>
<a href="mIDs.html">}</a>
<a href="destname.html">PSet critical.txt = {</a> <a href="thresh.html">string threshold = "ERROR"</a>
<a href="defaults.html">PSet default = {</a> <a href="limits.html">int32 limit</a> = 10
<a href="limits.html">int32 timespan = 180</a>
<a href="defaults.html">}</a>
<a href="notimespan.html">PSet serious_matter = { int32 limit = 100000 }</a>
}
<a href="destname.html">PSet detailedInfo.txt = {</a> <a href="thresh.html">string threshold = "INFO"</a>
<a href="defaults.html">PSet default = {</a> <a href="limits.html">int32 limit = 10</a>
<a href="limits.html">int32 timespan = 60</a>
<a href="defaults.html">}</a>
<a href="severity.html">PSet WARNING = </a>{ <a href="limits.html">int32 limit = 100</a>
<a href="limits.html">int32 timespan = 60</a>
}
<a href="severity.html">PSet ERROR = </a>{ <a href="limits.html">int32 limit = 100</a>
<a href="limits.html">int32 timespan = 60</a>
}
<a href="mIDs.html">PSet trkwarning</a> = { <a href="limits.html">int32 limit = 20</a>
<a href="limits.html">int32 timespan = 1200</a>
}
<a href="mIDs.html">PSet unimportant</a> = { <a href="limits.html">int32 limit = 5</a> }
<a href="mIDs.html">PSet serious_matter</a> = { <a href="limits.html">int32 limit = 1000000</a> }
}
PSet cerr = { <a href="thresh.html">string threshold = "WARNING"</a> }
<a href="destname.html">PSet jobdebug.txt = {</a> <a href="defaults.html">PSet default = { </a><a href="limits.html">int32 limit = 1000000</a> <a href="mIDs.html">}</a>
}
<a href="destname.html">PSet anotherfile.txt = {</a> <a href="notimespan.html">PSet serious_matter = { int32 limit = 1000</a> }
}
<a href="defdefault.html">PSet default = { int32 limit = 10</a>
<a href="defdefault.html">int32 timespan = 60</a>
<a href="defdefault.html">}</a>
}
untracked PSet maxEvents = {untracked int32 input = 10}
path p = { sendSomeMessages }
module sendSomeMessages = MessageLoggerClient { }
source = EmptySource { }
}
</pre>
<a name="linelength">
<h2> Adjusting Linebreak Policy </h2>
By default, output destinations format the message, breaking the text (at
boundaries where there was a new item of information or an operator<<)
to avoid lines of greater than 80 columns.
<p>
If this is not the desired behavior (for example, if the output file will be
processed by an automated parsing tool which prefers each message to be on a
single line) then this can be controled in the .cfg file:
<pre>
process TEST = {
service = MessageLogger {
vstring destinations = { "detailedInfo.txt"
, "critical.txt"
}
PSet critical.txt = { <a href="linebreak.html">bool noLineBreaks = true</a> }
PSet detailedInfo.txt = { <a href="linebreak.html">int32 lineLength = 132</a> }
}
untracked PSet maxEvents = {untracked int32 input = 5}
path p = { myAnalysisModule }
module myAnalysisModule = ModuleThatIssuesMessages { }
source = EmptySource { }
}
</pre>
<p><center>
<img src="bar.gif"></center>
<p><center>
<a href="http://www.uscms.org/SoftwareComputing/index.html">
USCMS Software and Computing Home Page </a> -
<a href="MessageLogger.html">CMS MessageLogger Service Page</a>
</center>
<p>
<hr>
<address><a href="mailto:mf@fnal.gov">Mark Fischler</a></address>
<!-- hhmts start -->
Last modified: December 1, 2005
<!-- hhmts end -->
</body>
|