The CMS MessageLogger Service is meant to allow code in modules, other services, and other framework "scaffolding" to log messages to a unified message logging and statistics facility.

The MessageLogger Service captures and coordinates messages originating in multiple modules (which, under the CMS framework, will in general be running in multiple threads) into a specified set of destinations. The management of these destinations is based on the ZOOM Error Logger package developed at Fermilab.

All users of the MessageLogger service should read the section on Issuing Messages .

The behavior of the MessageLogger can be adjusted via lines in the job's configuration file (.cfg). Users wishing to customize the behavior of the MessageLogger should read the section on MessageLogger Parameters .

• Issuing Messages
• MessageLogger Parameters - Configuring Destinations and their filtering and formatting behaviors
• Obtaining Message Statistics
• OpenIssuesDiscussion wiki, concerning MessageLogger features wanted by CMS, is provided.
• Feature List -- and where to find documentation of how to use each feature.

Issuing Messages

  #include "FWCore/MessageLogger/interface/MessageLogger.h"

  service = MessageLogger { }

If the .cfg file does not specify the MessageLogger service, or if a message is issued in code executed before any services are initiated, then the response to issuing a message will be that the content will be sent to cerr. Having included the necessary MessageLogger header, when code wishes to issue a message, one of these functions can be used:

  edm::LogError   ("category") << a << b << ... << z;
  edm::LogWarning ("category") << a << b << ... << z;
  edm::LogInfo    ("category") << a << b << ... << z;

• LogInfo, LogWarning, and LogError represent three levels of "severity" of the message. It is possible (see MessageLogger Parameters ) to configure the job to ignore all LogInfo messages, or all messages of severity less than LogError.

  See CMS Guidelines for Messages and Categories for advice on which severity is appropriate, and on choosing category names.

• category should specify what this message is about. category is going to be included as the first part of the message, but it also plays two other roles:
  1. It is possible to set limits on how many times some specific type of message will be sent to the outputs of the logger. By "type" we mean any messages with some specific category. See MessageLogger Parameters for details.
  2. When message statistics are provided, the counts of how many times messages of a given type were issued are keyed to category, module label, and (if provided) subroutine.
• It is unnecessary to explicitly specify the module label or the run/event number; these are automatically provided by the logger.
• An arbitrary number of additional objects << a << b << ... << z can be appended to the message. These can be strings, ints, doubles, or any object that has an operator<< to an ostream. (Or the message can be issued with no additional objects at all.)
• There is no need to add spaces at the beginning or end of text items sent to the message, or to add text separators between numberical items. This spacing is taken care of by the logger.
• There is no need to affix any sort of endl; when the statement ends the message will be dispatched.
• Newline characters can be included in the objects appended to the message. These will be used in formatting the message. But they are generally not necessary: Line breaks are automatically inserted if the next appended object would cause the line to exceed 80 characters.

    LogDebug    ("category") << a << b << ... << z;

• LogDebug affixes the __FILE__ and __LINE__ number to the message.
• LogDebug messages are considered to be lower in severity than LogInfo messages.
• By default, LogDebug messages will be rapidly discarded with a minimum of overhead. The user must specify in the .cfg file LogDebug messages from various modules are to be enabled; see Controlling LogDebug Behavior: Enabling LogDebug Messages for how that is done.
• Because it must get __FILE__ and __LINE__ from the spot issuing the message, LogDebug is implemented as a macro rather than a free function.
• Because LogDebug is a macro, it is not prepended with the edm:: namespace designation.

Some other wrinkles about issuing messages:

• The category of a message can instead be a "compound" category, with individiual categories separated by a vertical bar (|), as in

    LogWarning("ReadoutError|TimeBudgetExceeded") << "Processed " << nitems 
                                                  << "items and ran out of time";
  

  Compound messges will be reported if any of the individual categories would be reported.
• The first item streamed to a message can optionally be of the form "@SUB=methodName" (note no spaces). This will indicate that the message came from that method; two messages from different "subroutines" are considered, for statistics and limits purposes, to be two different types of messages even if they are in the same category and from the same module.

Feature List

• Header file to include in code issuing messages -- Issuing Messages
• Issuing LogError, LogWarning, LogInfo and LogDebug Messages -- Issuing Messages
• Specifying that the MessageLogger service be configured -- Issuing Messages or MessageLogger Parameters
• Guidelines for assigning categories and shoosing which type of message to issue -- CMS Guidelines for Messages and Categories
• Messages can be assigned multiple categories -- Issuing Messages
• The module label will and run/event context will automatically be included in the reported message -- Issuing Messages
• There is an optional mechanism for specifying the method or subroutine from which the message has been issued -- Issuing Messages
• It is permissible for messages to be issued from code which may execute before the MessageLogger service has been configured -- Issuing Messages

Configuring destinations

• Specifying a destination for messages, which will write the messages to a file -- MessageLogger Parameters: Example .cfg file
• Specifying a destination for messages, which will write the messages to cerr or cout -- MessageLogger Parameters: Example .cfg file
• Specifying a destination which will forward messages to log4cplus -- MessageLogger Parameters: Routing Messages to log4cplus
• Specifying a threshold for a destination (for example, directing the destination to ignore LogInfo and LogDebug messages) -- MessageLogger Parameters: Example .cfg file
• Specifying limits on how many times a destination will respond to a given message category -- MessageLogger Parameters: Examples of Limits and Timespan Parameters
• Dictating the line-break policy followed by a destination -- MessageLogger Parameters: Adjusting Linebreak Policy

Debug messages

• Issuing LogDebug Messages -- Issuing Messages or Controlling LogDebug Behavior
• By default, LogDebug messages will efficiently be ignored -- Controlling LogDebug Behavior: Enabling LogDebug Messages
• Enabling all LogDebug messages -- Controlling LogDebug Behavior: Enabling all LogDebug Messages
• Enabling LogDebug messages issued by a specific module -- Controlling LogDebug Behavior: Enabling LogDebug Messages
• Lowering the threshold for a destination, so it will respond to enabled LogDebug messages -- Controlling LogDebug Behavior
• #define NDEBUG will cause compile-time elimination of LogDebug message overhead -- Controlling LogDebug Behavior: Compile-time Elimination of LogDebug Messages
• #define ML_NDEBUG to cause compile-time elimination of LogDebug message overhead when NDEBUG is not defined -- Controlling LogDebug Behavior: Compile-time Elimination of LogDebug Messages
• #define ML_DEBUG will force LogDebug compilation, even if NDEBUG is defined -- Controlling LogDebug Behavior: Compile-time Elimination of LogDebug Messages

Message Statistics

• Counts of various types of messages issued can be obtained -- Obtaining Message Statistics
• Statistics summaries are written automatically at end of job -- Obtaining Message Statistics
• Statistics destinations can be configured to use a specified severity threshold -- Obtaining Message Statistics
• Statistics destinations can write to their own file or share a file with an ordinary output destination -- Obtaining Message Statistics
• User code can trigger the statistics destinations to write out the statistics accumulated thus far -- Obtaining Message Statistics: The edm::LogStatistics() Function
• Each statistics destination can be configured to reset after each time the statistics are written out, or to continue accumulating further statistics -- Obtaining Message Statistics: The edm::LogStatistics() Function

Framework Job Reports

• Destinations can be declared which will write an xml version of the logged messages -- Framework Job Reports
• A fwkJobReport destination can be configured for limits and thresholds in the same manner as for other output destinations -- Framework Job Reports , MessageLogger Parameters