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: Obtaining Message Statistics
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 Obtaining Message Statistics</h1>
0014 </font>
0015 </center>
0016
0017 The MessageLogger service can provide statistics about the message issued
0018 during the course of a job. The information is placed in tables either at the
0019 end of a log file or in an individual file. The user code can also
0020 trigger statistics summaries of messages issued thus far --
0021 <br> see <a href="#LogStatistics"> The edm::LogStatistics() Function</a>
0022 <p>
0023 These statistics tables, written when the MessageLogger service encounters its
0024 postEndJob callback, include:
0025 <ul>
0026 <li>
0027 Counts of how many times a message with each combination of category,
0028 severity and module has been issued. (That is, if messages in the
0029 identical category are issued by two different modules, or one by LogWarning
0030 and another by LogInfo, these will be counted distinctly in the statistics.)
0031 <li>
0032 Samples of the run/event contexts for the first two and the last one message
0033 of each type that were issued.
0034 <li>
0035 Indications of whether there were any messages of a given type which were
0036 issued but were not reported (due to limits) by any destination.
0037 </ul>
0038
0039 <pre>
0040 process TEST =
0041 service = MessageLogger {
0042 vstring destinations = { "error_messages.txt" }
0043 vstring statistics = { "statistics.txt"
0044 , "another_stats"
0045 , "error_messages.txt"
0046 }
0047 PSet statistics.txt = { string threshold = "WARNING" }
0048 PSet anotherStats = { string output = "more_stats.txt" }
0049 PSet error_messages.txt = { string threshold = "ERROR" }
0050 }
0051 untracked PSet maxEvents = {untracked int32 input = 5}
0052 path p = { myAnalysisModule }
0053 module myAnalysisModule = ModuleThatIssuesMessages { }
0054 source = EmptySource { }
0055 }
0056 </pre>
0057
0058 The <font color=red>vstring statistics = { "statistics.txt"
0059 , "another_stats"
0060 , "error_messages.txt"
0061 }</font> directs the system to
0062 attach a three statistics destinations, to be controlled by parameter sets
0063 named statistics.txt, another_stats, and error_messages.txt. (Normally,
0064 only one statistics destination is desired; here we use three to illustrate
0065 various control options.)
0066 <p>
0067 <font color=red>
0068 PSet statistics.txt = { string threshold = "WARNING" } </font>
0069 directs statistics.txt to respond to (and keep track of) only
0070 LogError and LogWarning messages. Statistics destinations do not
0071 impose limits for each category (they only count the messages anyway)
0072 but they are sensitive to thresholds of which severities to report about.
0073 <p>
0074 <font color=red>
0075 PSet anotherStats = { string output = "more_stats.txt" }
0076 </font>
0077 directs the statistics destination controlled by the anotherStats PSet
0078 to write its output to the file more_stats.txt. If no output were specified,
0079 then the statistics destination would write its summary to a file with the
0080 name listed in the <code>statistics</code> vstring. For example, with the
0081 above .cfg file, the statistics.txt destination would write to
0082 statistics.txt.
0083 <p>
0084 <font color=red>
0085 PSet error_messages.txt = { string threshold = "ERROR" }
0086 </font>
0087 controls both the error_messages.txt output destination, and the
0088 error_messages.txt statistics destination. Thus that statistics destination
0089 will respond with a threshold of LogError, and will write its end-of-job
0090 summary to the end of the file error_messages.txt.
0091 <p>
0092 In general, any statistics destination whose output file name (as determined
0093 either by an explicit <code>output</code> string or implicitly as the
0094 same name used to control the destination) matches the file of an ordinary
0095 destination, will write its summary output at the end of that ordinary
0096 destination's file.
0097 <p><hr><p>
0098 Here is a sample statistics summary output:
0099 <pre>
0100 Process
0101 type category sev module subroutine count total
0102 ---- -------------------- -- ---------------- ---------------- ----- -----
0103 1 cat_A -w UnitTestClient_A 3* 3
0104 2 cat_B -w UnitTestClient_A 3* 3
0105 3 cat_A -e UnitTestClient_A 3 3
0106 4 cat_B -e UnitTestClient_A 3 3
0107
0108 * Some occurrences of this message were suppressed in all logs, due to limits.
0109
0110 type category Examples: run/evt run/evt run/evt
0111 ---- -------------------- ---------------- ---------------- ----------------
0112 1 cat_A 1/1 1/2 1/3
0113 2 cat_B 1/1 1/2 1/3
0114 3 cat_A 1/1 1/2 1/3
0115 4 cat_B 1/1 1/2 1/3
0116
0117 Severity # Occurrences Total Occurrences
0118 -------- ------------- -----------------
0119 Warning 6 6
0120 Error 6 6
0121 </pre>
0122
0123 <p><hr><p>
0124 <a name="LogStatistics">
0125 <h2>The edm::LogStatistics() Function</h2>
0126
0127 The user program can force each statistics destination to write its current
0128 message counts and summary to its file or stream, before the end of job
0129 automatically causes that writing. To do this, invoke the function
0130 <font color=blue>
0131 <pre>
0132 edm::LogStatistics();
0133 </pre>
0134 </font>
0135 (Just as for edm::LogError() and the other message commands, this function
0136 is defined by including <code>MessageLogger.h</code>).
0137 <p>
0138 While ordinary analysis code probably has no need to invoke this,
0139 one can use the framework's features to set up a sensible schedule of
0140 outputting statistics.
0141 For example, one can place a call to
0142 <font color=blue>edm::LogStatistics()</font>
0143 in a postRun callback.
0144 <p>
0145 The default behavior is to output the statistics thus far accumulated,
0146 and then to continue collecting statistics.
0147 If, for some statistics destination, it is preferable that the statistics
0148 be reset to zero after each summary output, this can be directed in the
0149 PSet for that statistics destination:
0150 <pre>
0151 process TEST =
0152 service = MessageLogger {
0153 vstring destinations = { "error_messages.txt" }
0154 vstring statistics = { "statistics.txt", "runstats.txt" }
0155 PSet statistics.txt = { string threshold = "WARNING" }
0156 <font color=red>PSet runstats.txt = { bool reset = true }</font>
0157 }
0158 untracked PSet maxEvents = {untracked int32 input = 5}
0159 path p = { myAnalysisModule }
0160 module myAnalysisModule = ModuleThatIssuesMessages { }
0161 source = EmptySource { }
0162 }
0163 </pre>
0164
0165 In this example, the statistics kept by
0166 <code>runstats.txt</code> will be reset after each statistics output
0167 triggered by <code>edm::LogStatistics()</code>.
0168 <p>
0169 Of course, the <code>bool reset</code> parameter is moot if the
0170 program never explicitly invokes <code>edm::LogStatistics()</code>, since
0171 it is immaterial whether the statistics are reset after the final automatic
0172 end-of-job summary is output.
0173
0174
0175
0176
0177
0178 <p><center>
0179 <img src="bar.gif"></center>
0180
0181 <p><center>
0182 <a href="http://www.uscms.org/SoftwareComputing/index.html">
0183 USCMS Software and Computing Home Page </a> -
0184 <a href="MessageLogger.html"> CMS MessageLogger Service Page </a> -
0185 <a href="parameters.html#example"> Configuration File </a>
0186 </center>
0187
0188 <p>
0189 <hr>
0190 <address><a href="mailto:mf@fnal.gov">Mark Fischler</a></address>
0191
0192 Last modified: November 29, 2005
0193
0194 </body>
0195
