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: CMS Guidelines for Messages and Categories
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 CMS Guidelines for Messages and Categories</h1>
0014 </font>
0015 </center>
0016
0017 Messages sent to the logger are identified by two basic dimensions: a
0018 severity and a category. There are four fixed severities; the MessageLogger
0019 can accept any string (of up to 20 letters) as a category.
0020 Here is some guidance for how to decide which
0021 severity to use, and which category to assign.
0022
0023 <h2> Severity </h2>
0024 The severity is embedded in the names of four basic functions, one for
0025 each level:
0026 <font color=blue>
0027 <pre>
0028 edm::LogError ("category") << a << b << ... << z;
0029 edm::LogWarning ("category") << a << b << ... << z;
0030 edm::LogInfo ("category") << a << b << ... << z;
0031 LogDebug ("category") << a << b << ... << z;
0032 </pre>
0033 </font>
0034
0035 Here are some guidelines for the use of the functions.
0036 <ol>
0037 <li>
0038 <font color=blue><code>LogDebug</code></font>:
0039 There will be no message formatting overhead if the
0040 debugging messages are not enabled, the statement
0041 will be able to be removed completely at compile time with the proper defines.
0042 <ul>
0043 <li> Use this anywhere you what to report state information about your
0044 algorithm that is useful for figuring
0045 out the behavior of the algorithm or reporting positions that the
0046 program has reached. Examples:
0047 <pre>
0048 LogDebug("SegmentFinder") << "Matching segment" << i
0049 << "in tracking volume" << vol;
0050 LogDebug("SegmentFinder") << "Starting to find candidates from"
0051 << numhits << "hits";
0052 </pre>
0053 <li>
0054 Use this for messages that should not normally be issued when
0055 running on a farm in production.
0056 </ul>
0057
0058 <li>
0059 <font color=blue><code>edm::LogDebug</code></font>:
0060 <ul>
0061 <li> Use this for low frequency or course-grained status reporting, such as
0062 <pre>
0063 edm::LogInfo("AlgoReport") << "Saw" << x << " Events";
0064 </pre>
0065 <li>Use this for status messages that would naturally be included in
0066 reports while running on a farm in production.
0067 </ul>
0068
0069 <li>
0070 <font color=blue><code>edm::LogWarning</code></font>:
0071 <ul>
0072 <li> Use this when an algorithm encounters a perverse
0073 situation that does not cause an exception
0074 to be thrown, but the person running the program should be well aware
0075 of. A simple example is
0076 <pre>
0077 edm::LogWarning("Convergence") << "Could not satisfy convergence criteria in"
0078 << iters << "iterations, continuing";
0079 edm::LogWarning("TooMuchData") << "Found" << x
0080 << "candidates, using only the top 100;
0081 </pre>
0082 </ul>
0083
0084 <li><font color=blue><code>edm::LogError</code></font>:
0085 This is only to be used to report errors that result from
0086 exceptions throws.
0087 <ul>
0088 <li>
0089 Do not use <font color=blue><code>edm::LogError</code></font>
0090 if you throw an exception - the system will make this call for you when
0091 the exception is caught. Put all
0092 the information that you want reported into the exception.
0093 <li>
0094 If you
0095 have a situation where you encounter
0096 an error, but cannot throw an exception (i.e. can only return a bad
0097 return code), then it may be appropriate to issue a message via
0098 <font color=blue><code>edm::LogError</code></font>
0099 </ul>
0100 </ol>
0101
0102
0103 <h2> Category </h2>
0104
0105 One use of the category is for filtering messages or observing messages
0106 types across all algorithms. The category
0107 concept matches that of the exception processing, where different
0108 actions can be taken based on excception category.
0109 When exceptions are caught by the framework, the category of the
0110 exception is used as the LogError
0111 category. Choosing general names for conditions will facitate filtering
0112 and output log browsing.
0113 <p>
0114 For errors and warnings, category name examples include:
0115 <pre>
0116 DataNotFound
0117 TooLittleData
0118 TooMuchData
0119 ReadoutError
0120 TimeBudgetExceeded
0121 </pre>
0122
0123 By convention, category names should be 20 characters or shorter.
0124 <p>
0125 A log message can be a member of more than one category using the syntax:
0126 <pre>
0127 edm::LogWarning("TooLittleData<font color=red>|</font>Tracking") << "...";
0128 </pre>
0129 Such "compound" categories can, of course, exceed 20 characters.
0130
0131 <p>
0132 For Info and Debug, category names can include the function that is
0133 being performed. Be aware, however, that the module label will automatically
0134 be affixed to the message, so explicitly placing that into the category or
0135 as an item in the message is superfluous.
0136 <p>
0137
0138
0139
0140 <p><center>
0141 <img src="bar.gif"></center>
0142
0143 <p><center>
0144 <a href="http://www.uscms.org/SoftwareComputing/index.html">
0145 USCMS Software and Computing Home Page </a> -
0146 <a href="MessageLogger.html">CMS MessageLogger Service Page</a>
0147 </center>
0148
0149 <p>
0150 <hr>
0151 <address><a href="mailto:jbk@fnal.gov">Jim Kowalkowski</a></address>
0152 <!-- hhmts start -->
0153 Last modified: January 5, 2006
0154 <!-- hhmts end -->
0155 </body>
