File indexing completed on 2024-04-06 12:12:43
0001 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
0002 <BODY bgcolor="FFFFFF">
0003 <title>
0004 CMS MessageLogger: Configuring the MessageLogger Service
0005 </title>
0006
0007 <center>
0008 <h1> <img src="header-public.gif" align="center"> </h1>
0009
0010 <font color=red>
0011 <h1>CMS MessageLogger Service
0012 <br>
0013 Configuring the MessageLogger Service</h1>
0014 </font>
0015 </center>
0016
0017 <p>
0018 The <a href="MessageLogger.html">CMS MessageLogger Service </a>
0019 is meant to allow code to log
0020 messages to a unified message logging
0021 and statistics facility.
0022 While reasonable default behaviors are provided,
0023 the behavior of the MessageLogger can be adjusted via lines in the
0024 job's configuration file (.cfg).
0025 <p>
0026 <ul>
0027 <li> <a href="#Concepts"> Message Logging Concepts </a>
0028 <li> <a href="#cms"> Routine MessageLogger Parameters </a>
0029 <li> <a href="#example"> Example .cfg File Exercising Some Options</a>
0030 <li> <a href="#log4cplus"> Routing Messages to log4cplus </a>
0031 <li> <a href="#debug"> Enable LogDebug Messages </a>
0032 <li> <a href="#complete"> Examples of Limits and Timespan Parameters </a>
0033 <li> <a href="#linelength"> Adjusting Linebreak Policy </a>
0034 <li> <a href="statistics.html"> Obtaining Message Statistics </a>
0035 </ul>
0036 <p>
0037
0038 <a name="concepts">
0039 <h2> Message Logging Concepts </h2>
0040
0041 To understand what sort of flexibility is available, it is useful to
0042 be familiar with the following concepts:
0043 <ul>
0044 <li><font color=blue><b> Destination
0045 </b></font>
0046 <ul>
0047 The MessageLogger is capable of routing messages to multiple
0048 <b>Destination</b>s.
0049 The behavior -- the nature of which messages would appear
0050 and which would be ignored -- can be controlled for each destination.
0051 At present, two types of <b>destination</b>s are supported:
0052 <ol>
0053 <li> Output files, the names of which can be specified in the job's
0054 .cfg file. (If the file specified already exists, the messages will
0055 be appended to the file.)
0056 <li> Streams <font color=blue><b>cerr</b></font> and
0057 <font color=blue><b>cout</b></font>. (Because our parameter set
0058 syntax treats these names specially, creation of an output <em>file</em>
0059 named cerr or cout is not supported.)
0060 </ol>
0061 </ul>
0062 <li><font color=blue><b> Message ID
0063 </b></font>
0064 <ul>
0065 Each message is given a category when issued. This is intended to represent
0066 what this message is about. For example, several messages
0067 with different detailed content could all be of type <b>tracking</b>.
0068 Limits can be imposed on the reporting of messages in a given category,
0069 and statistics can be obtained by category.
0070 </ul>
0071 <li><font color=blue><b> Severity
0072 </b></font>
0073 <ul>
0074 <font color=blue>LogDebug</font>,
0075 <font color=blue>edm::LogWarning</font>,
0076 <font color=blue>edm::LogInfo</font>, and
0077 <font color=blue>edm::LogError</font> produce messages with severity
0078 <font color=blue>DEBUG</font>,
0079 <font color=blue>WARNING</font>,
0080 <font color=blue>INFO</font>, and
0081 <font color=blue>ERROR</font> respectively.
0082 These are ordered with <font color=blue>DEBUG</font> as the lowest
0083 severity and <font color=blue>ERROR</font> as the highest.
0084 </ul>
0085 <li><font color=blue><b> Threshold
0086 </b></font>
0087 <ul>
0088 For any given destination, the .cfg file can specify that every
0089 message with a severity lower than a given <font color=blue>threshold</font>
0090 shall be ignored.
0091 <font color=green>By default, a destination will have a threshold of
0092 <font color=blue>INFO</font>; responses to messages issued via LogDebug
0093 can be enabled by setting a threshold to <font color=blue>DEBUG</font>.
0094 </font>
0095 </ul>
0096 <li><font color=blue><b> Limit
0097 </b></font>
0098 <ul>
0099 For each message category,
0100 or for messages in general, or for a specified severity
0101 level, the .cfg file can instruct the logger to ignore messages after some
0102 number (the <font color=blue>limit</font>) have been encountered.
0103 (Actually, beyond the applicable limit, an occasional further message will
0104 appear, based on an exponential backoff. Thus, if the a limit is set at
0105 5, and 100 messages of that id are issued, then that destination will react
0106 to the messages number 1, 2, 3, 4, 5, 10, 15, 25, 45, and 85.) A limit of
0107 zero will disable reporting that category of messages.
0108 </ul>
0109 <li><font color=blue><b> Timespan
0110 </b></font>
0111 <ul>
0112 When a limit is set, it is possible to specify that if no occurrences of that
0113 type of message are seen in some number of seconds (the
0114 <font color=blue>timespan</font>), then the count toward that limit is to
0115 be reset. Thus if you wish to suppress most of the thousands of warnings of
0116 some type expected at startup, but would like to know if another one happens
0117 after a gap of ten minutes, this can be specified as a timespan of 600.
0118 </ul>
0119 </ul>
0120 <p>
0121 The typical user may not be interested in specifying limits of how many times
0122 messages of types will be displayed.
0123 <font color=green> By default, the MessageLogger service
0124 will impose a limit of 5 occurrences of each category of
0125 LogInfo messages, except for framework event messages which will be
0126 unlimited. </font>
0127
0128
0129 output to each destination every messages meeting the severity threshold
0130 criteria specific for that destination. In fact, the user need not specify
0131 any thresholds; then every message will be output. And if the user does not
0132 specify any destinations, then a single destination of cerr is assumed.
0133 <p>
0134
0135 In the near future, concepts for establishing and/or controlling a destination
0136 involving the <font color=blue> log4cplus </font> service may also
0137 be listed here.
0138
0139
0140 <a name="cms">
0141 <h2> Routine MessageLogger Parameters </h2>
0142
0143 The following is a portion of a .cfg file requesting the MessageLogger
0144 Service, and setting up setting a destination which will write messages
0145 to the file <font color=blue>messages.txt</font>. The default threshold
0146 and limits will apply: No LogDebug messages will be reported, and
0147 only the first five messages of each category will be reported.
0148 <font color=blue>
0149 <pre>
0150 process TEST =
0151 {
0152 service = MessageLoggger { vstring destinations = { "messages.txt" } }
0153 }
0154 </pre>
0155 </font>
0156
0157
0158 <a name="example">
0159 <h2> Example .cfg File Exercising Some Options </h2>
0160
0161 The following is an example .cfg file, requesting the MessageLogger
0162 Service, setting up some destinations, and specifying some thresholds
0163 for how "severe" a message must be in order for it to appear in each
0164 destination.
0165
0166 <pre>
0167 process TEST = {
0168
0169 <a href="serviceML.html">service = MessageLogger</a> {
0170 <a href="files.html">vstring destinations = </a>{ <a href="filename.html">"detailedInfo.txt"</a>
0171 , <a href="filename.html">"critical.txt"</a>
0172 , <a href="cout.html">"cout"</a>
0173 , <a href="cerr.html">"cerr"</a>
0174 }
0175 <a href="filename.html">PSet critical.txt</a> = { <a href="errorthreshold.html">string threshold = "ERROR"</a> }
0176 <a href="filename.html">PSet detailedInfo.txt</a> = { <a href="infothreshold.html">string threshold = "INFO"</a> }
0177 <a href="cerr.html">PSet cerr</a> = { <a href="warnthreshold.html">string threshold = "WARNING"</a> }
0178 }
0179 untracked PSet maxEvents = {untracked int32 input = 5}
0180 path p = { myAnalysisModule }
0181 module myAnalysisModule = ModuleThatIssuesMessages { }
0182 source = EmptySource { }
0183 }
0184 </pre>
0185
0186 <a name="debug">
0187 <h2> Enabling LogDebug Messages </h2>
0188
0189 The following is a portion of a .cfg file appropriate for a job that will
0190 run code instrumented with many LogDebug messages. This hypothetical user
0191 cares only about those LogDebug messages in the category
0192 <font color=blue>interestingToMe</font> and, in this file, prefers not
0193 to see any other LogDebug or LogInfo messages.
0194
0195 <font color=blue>
0196 <pre>
0197 process TEST =
0198 {
0199 service = MessageLoggger
0200 {
0201 vstring destinations = { "debugmessages.txt" }
0202 vstring categories = { "interestingToMe" }
0203 vstring debugModules = { "*" }
0204 PSet debugmessages.txt = { string threshold = "DEBUG"
0205 PSet INFO = { int32 limit = 0 }
0206 PSet DEBUG = { int32 limit = 0 }
0207 PSet interestingToMe = {int32 limit = 10000000}
0208 }
0209 }
0210 </pre>
0211 </font>
0212
0213 By default, all LogDebug messages issued from any modules would be
0214 rapidly discarded. This user chooses to enable the LogDebug messages
0215 issued by all modules, via
0216 <font color=blue>vstring debugModules = { "*" }</font>. (Instead,
0217 LogDebugs from a set of specific modules could be enabled; see
0218 <a href="debug.html#enabling">
0219 Controlling LogDebug Behavior: Enabling LogDebug Messages </a> for details.
0220 <p>
0221 Even if LogDebug messages are not rapidly discarded, destination have
0222 a default threshold of <code>INFO</code>, so no LogDebug messages would be
0223 reported.
0224 Here, for the <code>debugmessages.txt</code> destination,
0225 the user causes LogDebug messages to be reported by
0226 <font color=blue>string threshold = "DEBUG"</font>.
0227 If the PSet for <code>debugmessages.txt</code> were to end there,
0228 all LogDebug messages would be reported by this destination.
0229 <p>
0230 This user, however, desires more selectivity.
0231 The next two lines establish that for any category of messages
0232 without its own limit specification, if the message has severity
0233 INFO or DEBUG, use a limit of zero (which means don't report those
0234 messages). Finally, the .cfg file overrides this for messages in the
0235 category <font color=blue>interestingToMe</font>, permitting messages of
0236 that category to be reported.
0237
0238 <a name="log4cplus">
0239 <h2> Routing Messages to log4cplus </h2>
0240
0241 The MessageLogger will route messages to <b><code>log4cplus</code></b>
0242 if the .cfg file requests the <b><code>MLlog4cplus</code></b> service.
0243 The following is an example .cfg file, requesting the
0244 <code>MLlog4cplus</code>
0245 service, and specifying a threshold
0246 for how "severe" a message must be in order for it to be routed to
0247 <code>log4cplus</code>.
0248
0249 <pre>
0250 process TEST = {
0251 <a href="log4cplus.html">service = MLlog4cplus</a>
0252 service = MessageLogger {
0253 vstring destinations = { "detailedInfo.txt" }
0254 <a href="log4cplus.html">PSet log4cplus = { string threshold = "ERROR" }</a>
0255 }
0256 untracked PSet maxEvents = {untracked int32 input = 5}
0257 path p = { myAnalysisModule }
0258 module myAnalysisModule = ModuleThatIssuesMessages { }
0259 source = EmptySource { }
0260 }
0261 </pre>
0262
0263 The four severities of MessageLogger messages correspond to the four
0264 directives for issuing to <code>log4cplus</code>. For instance,
0265 <code>LogWarning("category")</code> leads to a <code>LOG4CPLUS_WARN(...)</code>
0266 call.
0267 <p>
0268 <code>log4cplus</code> dispatches to "appenders". For example, a
0269 <code>fileAppender</code> may be established to write the text to
0270 a file, or a <code>consoleAppender</code> to write to the job console.
0271 It is up to the user code or configuration file to establish which
0272 appenders are wanted.
0273 In the current implementation,
0274 the <code>MLlog4cplus</code> service automatically
0275 establishes a <code>fileAppender</code> writing <code>log4cplus.ouput</code>.
0276
0277
0278 <a name="complete">
0279 <h2> Examples of Limits and Timespan Parameters </h2>
0280
0281 The following is an example .cfg file, requesting the MessageLogger
0282 Service, setting up some destinations, and specifying some
0283 choices for thresholds, and for limits and timespans applicable
0284 to severities, to specific
0285 message ID's, and to all non-specified (default) message ID's.
0286 <p>
0287 The .cfg file contains not only a list of files, but also a list of message
0288 ID's that the author wishes to control individually.
0289 <pre>
0290 process TEST = {
0291
0292 <a href="serviceMLc.html">service = MessageLogger {</a>
0293 <a href="destinations.html">vstring destinations = { "detailedInfo.txt"</a>
0294 <a href="destinations.html">, "critical.txt"</a>
0295 <a href="destinations.html">, "jobdebug.txt"</a>
0296 <a href="destinations.html">, "anotherfile.txt"</a>
0297 <a href="destinations.html">, "cout"</a>
0298 <a href="destinations.html">, "cerr"</a>
0299 <a href="destinations.html">}</a>
0300 <a href="mIDs.html">vstring categories = { "unimportant"</a>
0301 <a href="mIDs.html">, "trkwarning"</a>
0302 <a href="mIDs.html">, "serious_matter"</a>
0303 <a href="mIDs.html">}</a>
0304 <a href="destname.html">PSet critical.txt = {</a> <a href="thresh.html">string threshold = "ERROR"</a>
0305 <a href="defaults.html">PSet default = {</a> <a href="limits.html">int32 limit</a> = 10
0306 <a href="limits.html">int32 timespan = 180</a>
0307 <a href="defaults.html">}</a>
0308 <a href="notimespan.html">PSet serious_matter = { int32 limit = 100000 }</a>
0309 }
0310 <a href="destname.html">PSet detailedInfo.txt = {</a> <a href="thresh.html">string threshold = "INFO"</a>
0311 <a href="defaults.html">PSet default = {</a> <a href="limits.html">int32 limit = 10</a>
0312 <a href="limits.html">int32 timespan = 60</a>
0313 <a href="defaults.html">}</a>
0314 <a href="severity.html">PSet WARNING = </a>{ <a href="limits.html">int32 limit = 100</a>
0315 <a href="limits.html">int32 timespan = 60</a>
0316 }
0317 <a href="severity.html">PSet ERROR = </a>{ <a href="limits.html">int32 limit = 100</a>
0318 <a href="limits.html">int32 timespan = 60</a>
0319 }
0320 <a href="mIDs.html">PSet trkwarning</a> = { <a href="limits.html">int32 limit = 20</a>
0321 <a href="limits.html">int32 timespan = 1200</a>
0322 }
0323 <a href="mIDs.html">PSet unimportant</a> = { <a href="limits.html">int32 limit = 5</a> }
0324 <a href="mIDs.html">PSet serious_matter</a> = { <a href="limits.html">int32 limit = 1000000</a> }
0325 }
0326 PSet cerr = { <a href="thresh.html">string threshold = "WARNING"</a> }
0327
0328 <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>
0329 }
0330 <a href="destname.html">PSet anotherfile.txt = {</a> <a href="notimespan.html">PSet serious_matter = { int32 limit = 1000</a> }
0331 }
0332 <a href="defdefault.html">PSet default = { int32 limit = 10</a>
0333 <a href="defdefault.html">int32 timespan = 60</a>
0334 <a href="defdefault.html">}</a>
0335 }
0336 untracked PSet maxEvents = {untracked int32 input = 10}
0337 path p = { sendSomeMessages }
0338 module sendSomeMessages = MessageLoggerClient { }
0339 source = EmptySource { }
0340 }
0341 </pre>
0342
0343 <a name="linelength">
0344 <h2> Adjusting Linebreak Policy </h2>
0345
0346 By default, output destinations format the message, breaking the text (at
0347 boundaries where there was a new item of information or an operator<<)
0348 to avoid lines of greater than 80 columns.
0349 <p>
0350 If this is not the desired behavior (for example, if the output file will be
0351 processed by an automated parsing tool which prefers each message to be on a
0352 single line) then this can be controled in the .cfg file:
0353 <pre>
0354 process TEST = {
0355
0356 service = MessageLogger {
0357 vstring destinations = { "detailedInfo.txt"
0358 , "critical.txt"
0359 }
0360 PSet critical.txt = { <a href="linebreak.html">bool noLineBreaks = true</a> }
0361 PSet detailedInfo.txt = { <a href="linebreak.html">int32 lineLength = 132</a> }
0362 }
0363 untracked PSet maxEvents = {untracked int32 input = 5}
0364 path p = { myAnalysisModule }
0365 module myAnalysisModule = ModuleThatIssuesMessages { }
0366 source = EmptySource { }
0367 }
0368 </pre>
0369
0370
0371 <p><center>
0372 <img src="bar.gif"></center>
0373
0374 <p><center>
0375 <a href="http://www.uscms.org/SoftwareComputing/index.html">
0376 USCMS Software and Computing Home Page </a> -
0377 <a href="MessageLogger.html">CMS MessageLogger Service Page</a>
0378 </center>
0379
0380 <p>
0381 <hr>
0382 <address><a href="mailto:mf@fnal.gov">Mark Fischler</a></address>
0383
0384 Last modified: December 1, 2005
0385
0386 </body>
