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: Guide To Issuing Messages
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 Guide To Issuing Messages</h1>
0014 </font>
0015 </center>
0016
0017 <p>
0018 The CMS MessageLogger Service is meant to allow code in modules, other
0019 services, and other framework "scaffolding" to log
0020 messages to a unified message logging
0021 and statistics facility.
0022 <p>
0023 The MessageLogger Service captures and coordinates messages originating in
0024 multiple modules (which, under the CMS framework, will in general be running
0025 in multiple threads) into a specified set of destinations.
0026 The management of these destinations is
0027 based on the ZOOM Error Logger package developed at Fermilab.
0028 <p>
0029 All users of the MessageLogger service should read the section on
0030 <a href="#howSend"> Issuing Messages </a>.
0031 <p>
0032 The behavior of the MessageLogger can be adjusted via lines in the
0033 job's configuration file (.cfg).
0034 Users wishing to customize the behavior of the MessageLogger should read
0035 the section on
0036 <a href="parameters.html"> MessageLogger Parameters </a>.
0037
0038 <p>
0039 <ul>
0040 <li> <a href="#howSend"> Issuing Messages </a>
0041 <li><a href="parameters.html"> MessageLogger Parameters </a> - Configuring
0042 Destinations and their filtering and formatting behaviors
0043 <li><a href="statistics.html"> Obtaining Message Statistics </a>
0044 <li> <a href="http://uimon.cern.ch/twiki/bin/view/CMS/OpenIssuesDiscussion">
0045 OpenIssuesDiscussion wiki</a>, concerning MessageLogger features wanted by CMS,
0046 is provided.
0047 <li> <a href="#features">Feature List</a> -- and where to find documentation of
0048 how to use each feature.
0049 </ul>
0050
0051 <hr><p></hr>
0052
0053 <a name="howSend">
0054 <p>
0055 <h2> Issuing Messages </h2>
0056
0057 In order to issue messages, the module must include the MessageLogger
0058 service header:
0059 <font color=blue>
0060 <pre>
0061 #include "FWCore/MessageLogger/interface/MessageLogger.h"
0062 </pre>
0063 </font>
0064
0065 In addition, it is strongly recommended (for consistency with the way all
0066 services are used ) that the .cfg file contain at least the line
0067 <font color=blue>
0068 <pre>
0069 service = MessageLogger { }
0070 </pre>
0071 </font>
0072 The braces can enclose specifications of parameters to adjust the
0073 MessageLogger behavior
0074 (see <a href="parameters.html"> MessageLogger Parameters </a>);
0075 if no parameters are supplied, a sensible CMS default behavior is
0076 provided.
0077 <p>
0078 <a name="preconfig">
0079 If the .cfg file does not specify the MessageLogger service,
0080 or if a message is issued in code executed before any services are initiated,
0081 then the response to issuing a message will be that the content will
0082 be sent to cerr.
0083
0084 Having included the necessary MessageLogger header, when code wishes to issue
0085 a message, one of these functions can be used:
0086
0087 <font color=blue>
0088 <pre>
0089 edm::LogError ("category") << a << b << ... << z;
0090 edm::LogWarning ("category") << a << b << ... << z;
0091 edm::LogInfo ("category") << a << b << ... << z;
0092 </pre>
0093 </font>
0094 When issuing messages:
0095 <ul>
0096 <li>
0097 <font color=blue>LogInfo</font>, <font color=blue>LogWarning</font>,
0098 and <font color=blue>LogError</font>
0099 represent three levels of "severity" of the message. It is possible
0100 (see <a href="parameters.html"> MessageLogger Parameters </a>)
0101 to configure the job to ignore all <font color=blue>LogInfo</font> messages,
0102 or all messages of severity less than <font color=blue>LogError</font>.
0103 <p>
0104 See <a href="guidelines.html">CMS Guidelines for Messages and Categories</a>
0105 for advice on which severity
0106 is appropriate, and on choosing category names.
0107 <li>
0108 <font color=blue>category</font> should specify what this message is about.
0109 <font color=blue>category</font> is going to be included as the first
0110 part of the message, but it also plays two other roles:
0111 <ol>
0112 <li> It is possible to set limits on how many times some specific
0113 type of message will be sent to the outputs of the logger.
0114 By "type" we mean any messages with some specific category. See
0115 <a href="parameters.html"> MessageLogger Parameters</a> for details.
0116 <li> When message statistics are provided, the counts of how many times
0117 messages of a given type were issued are keyed to category, module label,
0118 and (if provided) subroutine.
0119 </ol>
0120 <a name="modulelable">
0121 <li> It is unnecessary to explicitly specify the module label or the run/event number;
0122 these are automatically provided by the logger.
0123 <li>
0124 An arbitrary number of additional
0125 objects <font color=blue> << a << b << ... << z </font> can be
0126 appended to the message. These can be strings, ints, doubles, or any object
0127 that has an <b>operator<< </b> to an ostream.
0128 (Or the message can be issued with no additional objects at all.)
0129 <li>
0130 There is no need to add spaces at the beginning or end of text items sent to the message,
0131 or to add text separators between numberical items. This spacing is taken care of by the logger.
0132 <li>
0133 There is no need to affix any sort of <b>endl</b>; when the
0134 statement ends the message will be dispatched.
0135 <li> Newline characters can be included in the objects appended to the message.
0136 These will be used in formatting the message. But they are generally not
0137 necessary: Line breaks are automatically inserted if the next appended
0138 object would cause the line to exceed 80 characters.
0139 </ul>
0140
0141 <a name="logdebug">
0142 There is an additional form for issuing a message:
0143 <font color=blue>
0144 <pre>
0145 LogDebug ("category") << a << b << ... << z;
0146 </pre>
0147 </font>
0148 This is identical to the others, except:
0149 <ul>
0150 <li>
0151 <font color=blue>LogDebug</font>
0152 affixes the <b>__FILE__</b> and <b>__LINE__</b> number to the
0153 message.
0154 <li>
0155 LogDebug messages are considered to be lower in severity than LogInfo
0156 messages.
0157 <li>
0158 By default, LogDebug messages will be rapidly discarded with a minimum of overhead.
0159 The user must specify in the .cfg file LogDebug messages from various modules are
0160 to be enabled;
0161 see <a href="debug.html#enabling">
0162 Controlling LogDebug Behavior: Enabling LogDebug Messages </a> for how
0163 that is done.
0164 <li>
0165 Because it must get <b>__FILE__</b> and <b>__LINE__</b> from the spot
0166 issuing the message, <font color=blue>LogDebug</font>
0167 is implemented as a macro rather than a free function.
0168 <li>
0169 Because <font color=blue>LogDebug</font> is a macro, it is not
0170 prepended with the <font color=blue>edm::</font> namespace
0171 designation.
0172 </ul>
0173
0174 <p>
0175 Some other wrinkles about issuing messages:
0176 <ul>
0177 <a name="compound">
0178 <li>
0179 The category of a message can instead be a "compound" category, with individiual
0180 categories separated by a vertical bar (|), as in
0181 <pre>
0182 LogWarning("ReadoutError<a font color=red>|</a>TimeBudgetExceeded") << "Processed " << nitems
0183 << "items and ran out of time";
0184 </pre>
0185 Compound messges will be reported if any of the individual categories would be reported.
0186 <a name="sub">
0187 <li> The first item streamed to a message can optionally be of the form
0188 <font color=blue><code>"@SUB=methodName"</code></font> (note no spaces).
0189 This will indicate that the message came from that method;
0190 two messages from different "subroutines" are considered, for statistics and
0191 limits purposes, to be two different types of messages even if they are in the same
0192 category and from the same module.
0193 </ul>
0194
0195 <hr><p></hr>
0196
0197 <a name="features">
0198 <p>
0199 <h2> Feature List </h2>
0200
0201 <h3>Issuing messages</h3>
0202 <ul>
0203 <li>
0204 Header file to include in code issuing messages --
0205 <a href="#howSend"> Issuing Messages </a>
0206 <li>
0207 Issuing LogError, LogWarning, LogInfo and LogDebug Messages --
0208 <a href="#howSend"> Issuing Messages </a>
0209 <li>
0210 Specifying that the MessageLogger service be configured --
0211 <a href="#howSend"> Issuing Messages </a>
0212 or
0213 <a href="parameters.html#cms"> MessageLogger Parameters </a>
0214 <li>
0215 Guidelines for assigning categories and shoosing which type of message to issue --
0216 <a href="guidelines.html"> CMS Guidelines for Messages and Categories </a>
0217 <li>
0218 Messages can be assigned multiple categories --
0219 <a href="#compound"> Issuing Messages </a>
0220 <li>
0221 The module label will and run/event context will automatically be included in the
0222 reported message --
0223 <a href="#modulelabel"> Issuing Messages </a>
0224 <li>
0225 There is an optional mechanism for specifying the method or subroutine from which the
0226 message has been issued --
0227 <a href="#sub"> Issuing Messages </a>
0228 <li>
0229 It is permissible for messages to be issued from code which may execute
0230 before the MessageLogger service has been configured --
0231 <a href="#preconfig"> Issuing Messages </a>
0232 </ul>
0233
0234 <h3>Configuring destinations</h3>
0235 <ul>
0236 <li>
0237 Specifying a destination for messages, which will write the messages to a file --
0238 <a href="parameters.html#example"> MessageLogger Parameters: Example .cfg file </a>
0239 <li>
0240 Specifying a destination for messages, which will write the messages to
0241 cerr or cout --
0242 <a href="parameters.html#example"> MessageLogger Parameters: Example .cfg file </a>
0243 <li>
0244 Specifying a destination which will forward messages to log4cplus --
0245 <a href="parameters.html#log4cplus"> MessageLogger Parameters: Routing Messages to log4cplus </a>
0246 <li>
0247 Specifying a threshold for a destination (for example, directing the destination to ignore
0248 LogInfo and LogDebug messages) --
0249 <a href="parameters.html#example"> MessageLogger Parameters: Example .cfg file </a>
0250 <li>
0251 Specifying limits on how many times a destination will respond to a given message category --
0252 <a href="parameters.html#complete"> MessageLogger Parameters:
0253 Examples of Limits and Timespan Parameters</a>
0254 <li>
0255 Dictating the line-break policy followed by a destination --
0256 <a href="parameters.html#linelength"> MessageLogger Parameters:
0257 Adjusting Linebreak Policy</a>
0258 </ul>
0259 <h3>Debug messages</h3>
0260 <ul>
0261 <li>
0262 Issuing LogDebug Messages --
0263 <a href="#logdebug"> Issuing Messages </a>
0264 or
0265 <a href="debug.html"> Controlling LogDebug Behavior </a>
0266 <li>
0267 By default, LogDebug messages will efficiently be ignored --
0268 <a href="debug.html#enabling"> Controlling LogDebug Behavior: Enabling LogDebug Messages</a>
0269 <li>
0270 Enabling all LogDebug messages --
0271 <a href="debug.html#star"> Controlling LogDebug Behavior: Enabling all LogDebug Messages</a>
0272 <li>
0273 Enabling LogDebug messages issued by a specific module --
0274 <a href="debug.html#enabling"> Controlling LogDebug Behavior: Enabling LogDebug Messages</a>
0275 <li>
0276 Lowering the threshold for a destination, so it will respond to enabled LogDebug messages --
0277 <a href="debug.html#enabling"> Controlling LogDebug Behavior </a>
0278 <li>
0279 <code>#define NDEBUG</code> will cause compile-time elimination of LogDebug message overhead --
0280 <a href="debug.html#ML_NDEBUG"> Controlling LogDebug Behavior:
0281 Compile-time Elimination of LogDebug Messages </a>
0282 <li>
0283 <code>#define ML_NDEBUG</code> to cause compile-time elimination of LogDebug message overhead
0284 when <code>NDEBUG</code> is not defined --
0285 <a href="debug.html#ML_NDEBUG"> Controlling LogDebug Behavior:
0286 Compile-time Elimination of LogDebug Messages </a>
0287 <li>
0288 <code>#define ML_DEBUG</code> will force LogDebug compilation,
0289 even if <code>NDEBUG</code> is defined --
0290 <a href="debug.html#ML_NDEBUG"> Controlling LogDebug Behavior:
0291 Compile-time Elimination of LogDebug Messages </a>
0292 </ul>
0293
0294 <h3>Message Statistics</h3>
0295 <ul>
0296 <li> Counts of various types of messages issued can be obtained --
0297 <a href="statistics.html"> Obtaining Message Statistics </a>
0298 <li> Statistics summaries are written automatically at end of job --
0299 <a href="statistics.html"> Obtaining Message Statistics </a>
0300 <li> Statistics destinations can be configured to use a specified
0301 severity threshold --
0302 <a href="statistics.html"> Obtaining Message Statistics </a>
0303 <li> Statistics destinations can write to their own file or share a file
0304 with an ordinary output destination --
0305 <a href="statistics.html"> Obtaining Message Statistics </a>
0306 <li> User code can trigger the statistics destinations to write out
0307 the statistics accumulated thus far --
0308 <a href="statistics.html#LogStatistics">
0309 Obtaining Message Statistics: The edm::LogStatistics() Function </a>
0310 <li> Each statistics destination can be configured to reset after each
0311 time the statistics are written out, or to continue accumulating further
0312 statistics --
0313 <a href="statistics.html#LogStatistics">
0314 Obtaining Message Statistics: The edm::LogStatistics() Function </a>
0315 </ul>
0316
0317 <h3>Framework Job Reports</h3>
0318 <ul>
0319 <li> Destinations can be declared which will write an xml version of the
0320 logged messages -- <a href="fwkJobReport.html"> Framework Job Reports </a>
0321 <li> A <code>fwkJobReport</code> destination can be configured for limits and
0322 thresholds in the same
0323 manner as for other output destinations --
0324 <a href="fwkJobReport.html"> Framework Job Reports </a>,
0325 <a href="parameters.html#example"> MessageLogger Parameters </a>
0326 </ul>
0327
0328 <p><center>
0329 <img src="bar.gif"></center>
0330
0331 <p><center>
0332 <a href="https://uimon.cern.ch/twiki/bin/view/CMS/EDM">
0333 CMS Framework/EDM Wiki </a>
0334 </center>
0335
0336 <p>
0337 <hr>
0338 <address><a href="mailto:mf@fnal.gov">Mark Fischler</a></address>
0339 <!-- hhmts start -->
0340 Last modified: November 24, 2005
0341 <!-- hhmts end -->
0342 </body>
