CMS MessageLogger Service: CMS Guidelines for Messages and Categories

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 as a category (though only the first 20 characters will appear in summary table outputs). Here is some guidance for how to decide which severity to use, and which category to assign.

Severity

The severity is embedded in the names of four basic functions, one for each level:
  edm::LogError   ("category") << a << b << ... << z;
  edm::LogWarning ("category") << a << b << ... << z;
  edm::LogInfo    ("category") << a << b << ... << z;
       LogDebug   ("category") << a << b << ... << z;

For each of these severity levels, there is also another basic function, identical in every way except that these will inhibit all formatting and headers of the message which would be done by the logger:

  edm::LogProblem ("category") << a << b << ... << z;
  edm::LogPrint   ("category") << a << b << ... << z;
  edm::LogVerbatim("category") << a << b << ... << z;
       LogTrace   ("category") << a << b << ... << z;

In general, the headers and trailing %MSG indicators for each message are useful to people trying to help with various issues. Therefore, the non-formatting functions to issue messages should be used only in cases where the user has prepared a meaningful layout for a message (for example, a table might be included) and judges that the header would have an unacceptable impact on readability.

Here are some guidelines for the use of the various logging functions.

  1. LogDebug:
    LogTrace:
      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.

    • 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:
        LogDebug("SegmentFinder") << "Matching segment" << i 
                                  << "in tracking volume" << vol;
        LogDebug("SegmentFinder") << "Starting to find candidates from"
                                  << numhits << "hits";
      
      
    • Use this for messages that should not normally be issued when running on a farm in production.

  2. edm::LogInfo:
    edm::LogVerbatim:
    • Use this for low frequency or course-grained status reporting, of information of a routine nature, such as
        edm::LogInfo("AlgoReport") << "Saw" << x << " Events";
      
      
    • Messages of this severity will not routinely be included in reports while running on a grid in production.

  3. edm::LogWarning:
    edm::LogPrint:
    • 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
        edm::LogWarning("Convergence") << "Could not satisfy convergence criteria in" 
                                       << iters << "iterations, continuing";
        edm::LogWarning("TooMuchData") << "Found" << x 
                                       << "candidates, using only the top 100;
      
      
    • Caretakers of production jobs run on the grid will see LogWarning messages. Please do not inundate them with messages that express situations which are not intended to eventually be corrected, or with other information which they should not be concerned about.

  4. edm::LogError:
    edm::LogProblem:
      This is only to be used to report errors that result from exceptions throws.
    • Do not use edm::LogError

      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.

    • 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 edm::LogError

Users examining MessageLogger.h will see two additional severity levels:

  edm::LogSystem
  edm::LogAbsolute
The use of these is restricted to services and modules in the CMS EDM and Framework. Such messages will provide absoulute output without regard to limits or thresholds; use by non-framework modules is extremely frowned upon.

Category

One use of the category is for filtering messages or observing message 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.

For errors and warnings, category name examples include:

 
  DataNotFound
  TooLittleData
  TooMuchData
  ReadoutError
  TimeBudgetExceeded

By convention, category names should be 20 characters or shorter. Category names of up to 200 characters will work fine, but only the first 20 characters will be displayed in message statistics tables. Category names longer than 200 characters should not be used.

Category names can contain any combination of letters, numbers and underscores. Due to the need to be parsed as PSet names in the configuration file, and to be used and possibly combined when issuing messages, category names:

  • Should not contain blanks spaces or tabs.
  • Should not contain other special characters. In particular

    / , \ , . , [ , " , { ,

    } , = , - , |
    are known to be problematic if used in category names.

  • The category name is not allowed to contain a slash /

    or a backslash \ . (Yes, we know this is a redundant warning.)

A log message can be a member of more than one category using the syntax:

  edm::LogWarning("TooLittleData|Tracking") << "...";
Such "compound" categories can, of course, exceed 20 characters.

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.

Composing the Message

The content of the message depends, of course, on the information you need to convey. However, because these messages will appear in a stream together with messages issued by others, the following guidelines are provided:

  • Information which repeats information present in the message header (including date/time and module label) is discouraged.
  • Please prefer to use the formatted logging functions rather than to create your own format which includes the information which would be in the standard header.
  • "ASCII art", included in a message to help it "stand out" from other messages, is strongly discouraged. This includes multiple line feeds, dashes across the page, rows of plus signs and so forth. Such techniques inevitably lead to escalating "ad-wars" and in the long run nobody is helped.


    Choosing category names which will assist in automated searching for particular sorts of messages is a good alternative.

-- SudhirMalik - 30-Aug-2011

Edit | Attach | Watch | Print version | History: r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r1 - 2011-08-30 - SudhirMalik
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback