|
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
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<BODY bgcolor="FFFFFF">
<title>
CMS MessageLogger: Controlling LogDebug Behavior
</title>
<center>
<h1> <img src="header-public.gif" align="center"> </h1>
<font color=red>
<h1>CMS MessageLogger Service
<br>
Controlling LogDebug Behavior</h1>
</font>
</center>
<p>
Code in user modules can be instrumented with LogDebug messages, intended
for use when abnormal circumstances require the output of detailed information.
In order that this instrumentation can be left in place
without impacting performance under normal circmstances,
it is important that LogDebug messages, by default, cost as little as possible
in runtime overhead.
That includes:
<ul>
<li> Avoiding sending the messages through the logic that gives each
destination a chance to respond.
<li> Measures to eliminate almost all of the cost of processing the
operator<< operations that stream text or other items to the message.
</ul>
<p>
Since LogDebug messages are (by default) rapidly discarded,
the user can explicitly enable LogDebug messages issued by
some or all modules. This is done without needing to re-compile
code, via parameters in the .cfg file.
<p>
For time-critical running, there is also a way to elminate the effect of
LogDebug messages at compile-time. When this approach is used, the
LogDebug calls will be optimized down to be truly zero-cost. The trade-off
is that for code compiled with this switch set, the LogDebug messages cannot
be explicitly enabled via parameters in the .cfg file.
<p>
<ul>
<li>
<a href="#enabling"> Enabling LogDebug Messages </a>
<li>
<a href="#ML_NDEBUG"> Compile-time Elimination of LogDebug Messages
<li>
<a href="#why"> Why are my LogDebug Messages Not Being Reported?
</ul>
<p><hr><p>
<a name="enabling">
<h2> Enabling LogDebug Messages </h2>
Code can be freely sprinkled with LogDebug messages, without fear of undue
performance overhead: By default, each call to LogDebug("category") will
consult a boolean variable to check whether debug messages are enabled for
the current module. Unless debug messages have explicitly been enabled,
LogDebug() will do no other work, and each operator<< to the LogDebug
will merely check that same boolean and do no work either.
<p>
In order to "turn on" responses to LogDebug, the user does two things in the
.cfg file, as illustrated by this example:
<pre>
process TEST = {
service = MessageLogger {
vstring destinations = { "detailedInfo.txt"
, "critical.txt"
}
PSet detailedInfo.txt = { <font color=red>string threshold = "DEBUG" </font> }
<font color=red>vstring debugModules = { "myAnalysisModule"
, "myOtherModule
}</font>
}
untracked PSet maxEvents = {untracked int32 input = 5}
path p = { myAnalysisModule, myOtherModule, aThirdModule }
module myAnalysisModule = ModuleThatIssuesDebugMessages { }
module myOtherModule = ModuleThatIssuesDebugMessages { }
module aThirdModule = ModuleThatIssuesDebugMessages { }
source = EmptySource { }
}
</pre>
The <code><font color=red>string threshold = "DEBUG" </font></code>
parameter in the Pset for <code>detailedInfo.txt</code> specifies that
the destination writing to that file should respond to all messages of
severity DEBUG or higher -- that is, to all messages. By default
the threshold is <code>INFO</code>, so in the above example,
the destination writing to <code>critical.txt</code>
would not report the LogDebug
messages.
<p>
The <code><font color=red>vstring debugModules = {...}</font></code>
list specifies all the modules for which LogDebug should be enabled.
As illustrated, these modules are specified by their module labels.
In this example, LogDebug messages issued while in
<code>myAnalysisModule</code> or <code>myOtherModule</code> would be enabled,
while those issued while in <code>aThirdModule</code> would be rapidly
discarded.
<p>
<a name="star">
<h3> Enabling all LogDebug Messages </h3>
One further syntax is provided, for the convenience of users wishing to enable
all LogDebug messages:
<pre>
process TEST = {
service = MessageLogger {
vstring destinations = { "detailedInfo.txt"
, "critical.txt"
}
PSet detailedInfo.txt = { string threshold = "DEBUG" }
<font color=red>vstring debugModules = { "*" } </font>
}
untracked PSet maxEvents = {untracked int32 input = 5}
path p = { myAnalysisModule, myOtherModule, aThirdModule }
module myAnalysisModule = ModuleThatIssuesDebugMessages { }
module myOtherModule = ModuleThatIssuesDebugMessages { }
module aThirdModule = ModuleThatIssuesDebugMessages { }
source = EmptySource { }
}
</pre>
(Remember that you still have to set one or more thresholds to
<code>DEBUG</code>.
Unless some destination(s) have their thresholds set at
<code>DEBUG</code>, the LogDebug messages will be composed but no destination
will report them.)
<p>
<a name="ML_NDEBUG">
<h2> Compile-time Elimination of LogDebug Messages </h2>
If <code>NDEBUG</code> is defined (this is the same <code>NDEBUG</code> that
would turn <code>assert</code> into nothingness), then the LogDebug macro
will be transformed into a form that is easily optimized down to zero run-time
cost.
<p>
If the code was compiled with <code>NDEBUG</code> defined, LogDebug messages
will be completely suppressed (even if the .cfg file directs that they be
enabled), since the code for testing whether such messages are enabled will not
be present.
<p>
While the default behavior, as described above, is tied to the same
<code>NDEBUG</code> that applies to <code>assert</code> macros,
two additional symbols are provided to allow the user to over-ride
that behavior.
<ul>
<li>
If <code>ML_NDEBUG</code> is defined,
then LogDebug message code will not be compiled (that is, LogDebug will
be transformed into the zero-runtime-cost form) even if <code>NDEBUG</code>
is not defined.
<li>
If <code>ML_DEBUG</code> is defined,
then LogDebug message code will be compiled, not matter what.
</ul>
<a name="why">
<h2> Why are my LogDebug Messages Not Being Reported? </h2>
By design, the MessageLogger avoids (by default) reporting LogDebug
messages, and discards such messages as rapidly as possible unless
they are enabled. In addition, destinations' thresholds are set
above that of DEBUG severity by default; again, users must specifically
indicate that they want a destination to respond to LogDebug messages.
This design choice was made so that users can instrument their code with
(normally inactive) LogDebug diagnostics, and leave these in for future
use without impacting performance when the information is not needed.
<p>
A consequence of this policy is that there are several points at which
LogDebug message responses can be disabled, and the user requiring such
output needs to enable both the issuing and the reporting of the messages.
<p>
If you are trying to get your LogDebug messages to be reported and they are
not being shown, here is a checklist of reasons why LogDebug messages would
not be reported by a destination:
<ol>
<li>
If the code is compiled with the <code>NDEBUG</code> symbol defined
(for example, certain production compilations would do this to turn off
assert checking), then the <code>LogDebug</code> macro is turned to a no-op.
<p>
<em>You can define the symbol <code>ML_DEBUG</code> to override this.</em>
<p>
<li>
If the .cfg file does not explicitly enable LogDebug messages for a given
module, such messages issued by that module will be discarded. Make sure
the parameter
<font color=blue><code>vstring debugModules = { "myModuleLabel" }</code></font>
is present in the MessageLogger parameter set. Check the spelling of
<font color=blue><code>debugModules</code></font> and check that the module
label suppied is the correct label. This label will appear outside the
MessageLogger parameter set, on the left
side of a <font color=blue><code>module myModuleLabel =</code></font> parameter
and in the <font color=blue><code>path = { ..., myModuleLabel, ...}<code></font>
parameter.
<p>
<em> <font color=blue><code>vstring debugModules = { "*" }</code></font>
enables LogDebug messages from all modules.</em>
<p>
<li>
The threshold for every destination is, by default, set above the level that
would permit LogDebug messaes to be reported. In the parameter set for the
desired reporting destination, there must appear
<font color=blue><code>string threshold = "DEBUG"</code></font>
</ol>
<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>
|