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

FWCore/MessageLogger/doc/html/guidelines.html
155 строк5 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: CMS Guidelines for Messages and Categories
</title>

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

<font color=red>
<h1>CMS MessageLogger Service
<br> 
CMS Guidelines for Messages and Categories</h1>
</font>
</center>

Messages sent to the logger are identified by two basic dimensions: a
severity and a category.  There are four fixed severities; the MessageLogger
can accept any string (of up to 20 letters) as a category. 
Here is some guidance for how to decide which
severity to use, and which category to assign.

<h2> Severity </h2>
The severity is embedded in the names of four basic functions, one for
each level:
<font color=blue>
<pre>
  edm::LogError   ("category") << a << b << ... << z;
  edm::LogWarning ("category") << a << b << ... << z;
  edm::LogInfo    ("category") << a << b << ... << z;
       LogDebug   ("category") << a << b << ... << z;
</pre>
</font>

Here are some guidelines for the use of the functions. 
<ol>
<li>
<font color=blue><code>LogDebug</code></font>: 
There will be no message formatting overhead if the
debugging messages are not enabled, the statement
will be able to be removed completely at compile time with the proper defines.
<ul>
<li> Use this anywhere you what to report state information about your
algorithm that is useful for figuring
    out the behavior of the algorithm or reporting positions that the
program has reached. Examples:
<pre>
  LogDebug("SegmentFinder") << "Matching segment" << i 
                            << "in tracking volume" << vol;
  LogDebug("SegmentFinder") << "Starting to find candidates from"
                            << numhits << "hits";
</pre>
<li>
Use this for messages that should not normally be issued when
running on a farm in production.
</ul>                                                                                
 
<li>
<font color=blue><code>edm::LogDebug</code></font>: 
<ul>
<li> Use this for low frequency or course-grained status reporting, such as
<pre>
  edm::LogInfo("AlgoReport") << "Saw" << x << " Events";
</pre>
<li>Use this for status messages that would naturally be included in
reports while running on a farm in production.
</ul>

<li>                                                                               
<font color=blue><code>edm::LogWarning</code></font>: 
<ul>
<li> Use this when an algorithm encounters a perverse
situation that does not cause an exception
to be thrown, but the person running the program should be well aware
of.  A simple example is
<pre>
  edm::LogWarning("Convergence") << "Could not satisfy convergence criteria in" 
                                 << iters << "iterations, continuing";
  edm::LogWarning("TooMuchData") << "Found" << x 
                                 << "candidates, using only the top 100;
</pre>
</ul>
                                                                                
<li><font color=blue><code>edm::LogError</code></font>: 
This is only to be used to report errors that result from
exceptions throws.  
<ul>
<li>
Do not use <font color=blue><code>edm::LogError</code></font>
if you throw an exception - the system will make this call for you when
the exception is caught.  Put all
the information that you want reported into the exception.  
<li>
If you 
have a situation where you encounter
an error, but cannot throw an exception (i.e. can only return a bad
return code), then it may be appropriate to issue a message via
<font color=blue><code>edm::LogError</code></font> 
</ul>                                                                          
</ol>


<h2> Category </h2>

One use of the category is for filtering messages or observing messages
types across all algorithms.  The category
concept matches that of the exception processing, where different
actions can be taken based on excception category.
When exceptions are caught by the framework, the category of the
exception is used as the LogError
category. Choosing general names for conditions will facitate filtering
and output log browsing.
<p>                                                                                
For errors and warnings, category name examples include: 
<pre> 
  DataNotFound
  TooLittleData
  TooMuchData
  ReadoutError
  TimeBudgetExceeded
</pre>                                                                                

By convention, category names should be 20 characters or shorter.
<p>                                                                              
A log message can be a member of more than one category using the syntax:
<pre>
  edm::LogWarning("TooLittleData<font color=red>|</font>Tracking") << "...";
</pre>                                                                           
Such "compound" categories can, of course, exceed 20 characters.

<p>
For Info and Debug, category names can include the function that is
being performed.  Be aware, however, that the module label will automatically
be affixed to the message, so explicitly placing that into the category or 
as an item in the message is superfluous.
<p>



<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:jbk@fnal.gov">Jim Kowalkowski</a></address>
<!-- hhmts start -->
Last modified: January 5, 2006
<!-- hhmts end -->
</body>