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: Controlling LogDebug Behavior
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 Controlling LogDebug Behavior</h1>
0014 </font>
0015 </center>
0016
0017 <p>
0018
0019 Code in user modules can be instrumented with LogDebug messages, intended
0020 for use when abnormal circumstances require the output of detailed information.
0021 In order that this instrumentation can be left in place
0022 without impacting performance under normal circmstances,
0023 it is important that LogDebug messages, by default, cost as little as possible
0024 in runtime overhead.
0025 That includes:
0026 <ul>
0027 <li> Avoiding sending the messages through the logic that gives each
0028 destination a chance to respond.
0029 <li> Measures to eliminate almost all of the cost of processing the
0030 operator<< operations that stream text or other items to the message.
0031 </ul>
0032 <p>
0033 Since LogDebug messages are (by default) rapidly discarded,
0034 the user can explicitly enable LogDebug messages issued by
0035 some or all modules. This is done without needing to re-compile
0036 code, via parameters in the .cfg file.
0037 <p>
0038 For time-critical running, there is also a way to elminate the effect of
0039 LogDebug messages at compile-time. When this approach is used, the
0040 LogDebug calls will be optimized down to be truly zero-cost. The trade-off
0041 is that for code compiled with this switch set, the LogDebug messages cannot
0042 be explicitly enabled via parameters in the .cfg file.
0043 <p>
0044 <ul>
0045 <li>
0046 <a href="#enabling"> Enabling LogDebug Messages </a>
0047 <li>
0048 <a href="#ML_NDEBUG"> Compile-time Elimination of LogDebug Messages
0049 <li>
0050 <a href="#why"> Why are my LogDebug Messages Not Being Reported?
0051 </ul>
0052
0053 <p><hr><p>
0054 <a name="enabling">
0055 <h2> Enabling LogDebug Messages </h2>
0056
0057 Code can be freely sprinkled with LogDebug messages, without fear of undue
0058 performance overhead: By default, each call to LogDebug("category") will
0059 consult a boolean variable to check whether debug messages are enabled for
0060 the current module. Unless debug messages have explicitly been enabled,
0061 LogDebug() will do no other work, and each operator<< to the LogDebug
0062 will merely check that same boolean and do no work either.
0063 <p>
0064 In order to "turn on" responses to LogDebug, the user does two things in the
0065 .cfg file, as illustrated by this example:
0066
0067 <pre>
0068 process TEST = {
0069 service = MessageLogger {
0070 vstring destinations = { "detailedInfo.txt"
0071 , "critical.txt"
0072 }
0073 PSet detailedInfo.txt = { <font color=red>string threshold = "DEBUG" </font> }
0074 <font color=red>vstring debugModules = { "myAnalysisModule"
0075 , "myOtherModule
0076 }</font>
0077 }
0078 untracked PSet maxEvents = {untracked int32 input = 5}
0079 path p = { myAnalysisModule, myOtherModule, aThirdModule }
0080 module myAnalysisModule = ModuleThatIssuesDebugMessages { }
0081 module myOtherModule = ModuleThatIssuesDebugMessages { }
0082 module aThirdModule = ModuleThatIssuesDebugMessages { }
0083 source = EmptySource { }
0084 }
0085 </pre>
0086
0087 The <code><font color=red>string threshold = "DEBUG" </font></code>
0088 parameter in the Pset for <code>detailedInfo.txt</code> specifies that
0089 the destination writing to that file should respond to all messages of
0090 severity DEBUG or higher -- that is, to all messages. By default
0091 the threshold is <code>INFO</code>, so in the above example,
0092 the destination writing to <code>critical.txt</code>
0093 would not report the LogDebug
0094 messages.
0095 <p>
0096 The <code><font color=red>vstring debugModules = {...}</font></code>
0097 list specifies all the modules for which LogDebug should be enabled.
0098 As illustrated, these modules are specified by their module labels.
0099 In this example, LogDebug messages issued while in
0100 <code>myAnalysisModule</code> or <code>myOtherModule</code> would be enabled,
0101 while those issued while in <code>aThirdModule</code> would be rapidly
0102 discarded.
0103 <p>
0104 <a name="star">
0105 <h3> Enabling all LogDebug Messages </h3>
0106 One further syntax is provided, for the convenience of users wishing to enable
0107 all LogDebug messages:
0108 <pre>
0109 process TEST = {
0110 service = MessageLogger {
0111 vstring destinations = { "detailedInfo.txt"
0112 , "critical.txt"
0113 }
0114 PSet detailedInfo.txt = { string threshold = "DEBUG" }
0115 <font color=red>vstring debugModules = { "*" } </font>
0116 }
0117 untracked PSet maxEvents = {untracked int32 input = 5}
0118 path p = { myAnalysisModule, myOtherModule, aThirdModule }
0119 module myAnalysisModule = ModuleThatIssuesDebugMessages { }
0120 module myOtherModule = ModuleThatIssuesDebugMessages { }
0121 module aThirdModule = ModuleThatIssuesDebugMessages { }
0122 source = EmptySource { }
0123 }
0124 </pre>
0125 (Remember that you still have to set one or more thresholds to
0126 <code>DEBUG</code>.
0127 Unless some destination(s) have their thresholds set at
0128 <code>DEBUG</code>, the LogDebug messages will be composed but no destination
0129 will report them.)
0130
0131 <p>
0132 <a name="ML_NDEBUG">
0133 <h2> Compile-time Elimination of LogDebug Messages </h2>
0134
0135 If <code>NDEBUG</code> is defined (this is the same <code>NDEBUG</code> that
0136 would turn <code>assert</code> into nothingness), then the LogDebug macro
0137 will be transformed into a form that is easily optimized down to zero run-time
0138 cost.
0139 <p>
0140 If the code was compiled with <code>NDEBUG</code> defined, LogDebug messages
0141 will be completely suppressed (even if the .cfg file directs that they be
0142 enabled), since the code for testing whether such messages are enabled will not
0143 be present.
0144 <p>
0145 While the default behavior, as described above, is tied to the same
0146 <code>NDEBUG</code> that applies to <code>assert</code> macros,
0147 two additional symbols are provided to allow the user to over-ride
0148 that behavior.
0149 <ul>
0150 <li>
0151 If <code>ML_NDEBUG</code> is defined,
0152 then LogDebug message code will not be compiled (that is, LogDebug will
0153 be transformed into the zero-runtime-cost form) even if <code>NDEBUG</code>
0154 is not defined.
0155 <li>
0156 If <code>ML_DEBUG</code> is defined,
0157 then LogDebug message code will be compiled, not matter what.
0158 </ul>
0159
0160 <a name="why">
0161 <h2> Why are my LogDebug Messages Not Being Reported? </h2>
0162
0163 By design, the MessageLogger avoids (by default) reporting LogDebug
0164 messages, and discards such messages as rapidly as possible unless
0165 they are enabled. In addition, destinations' thresholds are set
0166 above that of DEBUG severity by default; again, users must specifically
0167 indicate that they want a destination to respond to LogDebug messages.
0168 This design choice was made so that users can instrument their code with
0169 (normally inactive) LogDebug diagnostics, and leave these in for future
0170 use without impacting performance when the information is not needed.
0171 <p>
0172 A consequence of this policy is that there are several points at which
0173 LogDebug message responses can be disabled, and the user requiring such
0174 output needs to enable both the issuing and the reporting of the messages.
0175 <p>
0176 If you are trying to get your LogDebug messages to be reported and they are
0177 not being shown, here is a checklist of reasons why LogDebug messages would
0178 not be reported by a destination:
0179 <ol>
0180 <li>
0181 If the code is compiled with the <code>NDEBUG</code> symbol defined
0182 (for example, certain production compilations would do this to turn off
0183 assert checking), then the <code>LogDebug</code> macro is turned to a no-op.
0184 <p>
0185 <em>You can define the symbol <code>ML_DEBUG</code> to override this.</em>
0186 <p>
0187 <li>
0188 If the .cfg file does not explicitly enable LogDebug messages for a given
0189 module, such messages issued by that module will be discarded. Make sure
0190 the parameter
0191 <font color=blue><code>vstring debugModules = { "myModuleLabel" }</code></font>
0192 is present in the MessageLogger parameter set. Check the spelling of
0193 <font color=blue><code>debugModules</code></font> and check that the module
0194 label suppied is the correct label. This label will appear outside the
0195 MessageLogger parameter set, on the left
0196 side of a <font color=blue><code>module myModuleLabel =</code></font> parameter
0197 and in the <font color=blue><code>path = { ..., myModuleLabel, ...}<code></font>
0198 parameter.
0199 <p>
0200 <em> <font color=blue><code>vstring debugModules = { "*" }</code></font>
0201 enables LogDebug messages from all modules.</em>
0202 <p>
0203 <li>
0204 The threshold for every destination is, by default, set above the level that
0205 would permit LogDebug messaes to be reported. In the parameter set for the
0206 desired reporting destination, there must appear
0207 <font color=blue><code>string threshold = "DEBUG"</code></font>
0208 </ol>
0209
0210
0211 <p><center>
0212 <img src="bar.gif"></center>
0213
0214 <p><center>
0215 <a href="http://www.uscms.org/SoftwareComputing/index.html">
0216 USCMS Software and Computing Home Page </a> -
0217 <a href="MessageLogger.html">CMS MessageLogger Service Page</a>
0218 </center>
0219
0220 <p>
0221 <hr>
0222 <address><a href="mailto:mf@fnal.gov">Mark Fischler</a></address>
0223 <!-- hhmts start -->
0224 Last modified: December 1, 2005
0225 <!-- hhmts end -->
0226 </body>
