FWCore/MessageLogger/doc/html/statistics.html - master - githubmirror/cmssw

FWCore/MessageLogger/doc/html/statistics.html
194 строки7 KB
Giulio Eulisse
Snapshot of CMSSW_6_2_0_pre8.
26 июн 2013, 18:12
26 июн 2013, 18:12214ab73
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<BODY bgcolor="FFFFFF">
<title>
          CMS MessageLogger: Obtaining Message Statistics
</title>

<center>
<h1> <img src="header-public.gif" align="center"> </h1>

<font color=red>
<h1>CMS MessageLogger Service
<br> 
Obtaining Message Statistics</h1>
</font>
</center>

The MessageLogger service can provide statistics about the message issued
during the course of a job.  The information is placed in tables either at the
end of a log file or in an individual file.  The user code can also 
trigger statistics summaries of messages issued thus far -- 
<br> see <a href="#LogStatistics"> The edm::LogStatistics() Function</a>
<p>
These statistics tables, written when the MessageLogger service encounters its
postEndJob callback, include:
<ul>
<li>
Counts of how many times a message with each combination of category, 
severity and module has been issued.  (That is, if messages in the
identical category are issued by two different modules, or one by LogWarning
and another by LogInfo, these will be counted distinctly in the statistics.)
<li>
Samples of the run/event contexts for the first two and the last one message
of each type that were issued.
<li>
Indications of whether there were any messages of a given type which were 
issued but were not reported (due to limits) by any destination.
</ul>

<pre>
process TEST = 
  service = MessageLogger {
    vstring destinations = { "error_messages.txt" }
    vstring statistics   = { "statistics.txt"
			   , "another_stats" 
			   , "error_messages.txt" 
			   }
    PSet statistics.txt       = { string threshold  = "WARNING"   }
    PSet anotherStats         = { string output = "more_stats.txt" }
    PSet error_messages.txt   = { string threshold  = "ERROR" }
  }
  untracked PSet maxEvents = {untracked int32 input = 5}
  path p = { myAnalysisModule }
  module myAnalysisModule = ModuleThatIssuesMessages { }
  source = EmptySource { }
}
</pre>

The <font color=red>vstring statistics = { "statistics.txt"
			   , "another_stats" 
			   , "error_messages.txt" 
			   }</font> directs the system to 
attach a three statistics destinations, to be controlled by parameter sets
named statistics.txt, another_stats, and error_messages.txt.  (Normally, 
only one statistics destination is desired; here we use three to illustrate 
various control options.)
<p>
<font color=red> 
PSet statistics.txt = { string threshold  = "WARNING" } </font>
directs statistics.txt to respond to (and keep track of) only 
LogError and LogWarning messages.  Statistics destinations do not
impose limits for each category (they only count the messages anyway)
but they are sensitive to thresholds of which severities to report about.
<p>
<font color=red> 
PSet anotherStats = { string output = "more_stats.txt" }
</font>
directs the statistics destination controlled by the anotherStats PSet
to write its output to the file more_stats.txt.  If no output were specified,
then the statistics destination would write its summary to a file with the
name listed in the <code>statistics</code> vstring.  For example, with the
above .cfg file, the statistics.txt destination would write to 
statistics.txt.  
<p>
<font color=red> 
PSet error_messages.txt   = { string threshold  = "ERROR" }
</font>
controls both the error_messages.txt output destination, and the
error_messages.txt statistics destination.  Thus that statistics destination
will respond with a threshold of LogError, and will write its end-of-job
summary to the end of the file error_messages.txt.
<p>
In general, any statistics destination whose output file name (as determined
either by an explicit <code>output</code> string or implicitly as the
same name used to control the destination) matches the file of an ordinary
destination, will write its summary output at the end of that ordinary
destination's file.
<p><hr><p>
Here is a sample statistics summary output:
<pre>
Process
 type     category        sev    module        subroutine        count    total
 ---- -------------------- -- ---------------- ----------------  -----    -----
    1 cat_A                -w UnitTestClient_A                       3*       3
    2 cat_B                -w UnitTestClient_A                       3*       3
    3 cat_A                -e UnitTestClient_A                       3        3
    4 cat_B                -e UnitTestClient_A                       3        3
 
* Some occurrences of this message were suppressed in all logs, due to limits.
 
 type    category    Examples: run/evt        run/evt          run/evt
 ---- -------------------- ---------------- ---------------- ----------------
    1 cat_A                1/1              1/2              1/3
    2 cat_B                1/1              1/2              1/3
    3 cat_A                1/1              1/2              1/3
    4 cat_B                1/1              1/2              1/3
 
Severity    # Occurrences   Total Occurrences
--------    -------------   -----------------
Warning                 6                   6
Error                   6                   6
</pre>

<p><hr><p>
<a name="LogStatistics">
<h2>The edm::LogStatistics() Function</h2>

The user program can force each statistics destination to write its current
message counts and summary to its file or stream, before the end of job 
automatically causes that writing.  To do this, invoke the function
<font color=blue>
<pre>
edm::LogStatistics();
</pre>
</font>
(Just as for edm::LogError() and the other message commands, this function
is defined by including <code>MessageLogger.h</code>).
<p>
While ordinary analysis code probably has no need to invoke this, 
one can use the framework's features to set up a sensible schedule of
outputting statistics.
For example, one can place a call to 
<font color=blue>edm::LogStatistics()</font>
in a postRun callback.
<p>
The default behavior is to output the statistics thus far accumulated,
and then to continue collecting statistics.  
If, for some statistics destination, it is preferable that the statistics
be reset to zero after each summary output, this can be directed in the 
PSet for that statistics destination:
<pre>
process TEST = 
  service = MessageLogger {
    vstring destinations = { "error_messages.txt" }
    vstring statistics   = { "statistics.txt", "runstats.txt" }
    PSet statistics.txt  = { string threshold  = "WARNING"   }
    <font color=red>PSet runstats.txt    = { bool reset = true }</font>
  }
  untracked PSet maxEvents = {untracked int32 input = 5}
  path p = { myAnalysisModule }
  module myAnalysisModule = ModuleThatIssuesMessages { }
  source = EmptySource { }
}
</pre>

In this example, the statistics kept by 
<code>runstats.txt</code> will be reset after each statistics output
triggered by <code>edm::LogStatistics()</code>.
<p>
Of course, the <code>bool reset</code> parameter is moot if the  
program never explicitly invokes <code>edm::LogStatistics()</code>, since
it is immaterial whether the statistics are reset after the final automatic
end-of-job summary is output.
 




<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> -
<a href="parameters.html#example"> Configuration File </a>
</center>

<p>
      <hr>
      <address><a href="mailto:mf@fnal.gov">Mark Fischler</a></address>
<!-- hhmts start -->
Last modified: November 29, 2005
<!-- hhmts end -->
</body>