Warning, /FWCore/MessageService/doc/MakingNewDefaults.txt is written in an unsupported language. File is not indexed.
0001 Making New "Hardwired" Defaults for the MessageLogger: A Tutorial Guide
0002 ------------------------------------------------------------------------
0003
0004 This document will show how to change MessageLogger default configuration
0005 parameters, and how to create a specialized set of defaults, selectable
0006 by doing cmsRun -mode whateverNameYouChoose.
0007
0008 ---
0009
0010 The MessageLogger has a set of "hardwired" defaults, for use when no
0011 MessageLogger configuration appears in the config file. These match
0012 the contents of the MessageLogger.cfi file.
0013
0014 Although these defaults are hardwired into code, it is recognized that
0015 changing circumstances and experience withthe framework will make necessary
0016 changes in the defaults. Therefore, the defaults are kept in a clean form
0017 in one place, for ease of modification.
0018
0019 Multiple sets of these defaults can be provided, corresponding to multiple
0020 "modes" of operation. For example, the production running (which is in a
0021 sense the "default" default mode) might be interested only in warnings
0022 and errors, while occasional release validation jobs might want output
0023 concerning info messages as well. In the example below, we will show how to
0024
0025 a) Change the default summary threshold for the existing default mode.
0026 b) Create a new mode, with a different summary threshold.
0027
0028 If you are changing the main default (that is, the one gotten wheen no mode
0029 is specified), it is probably a good idea to change the MessageLogger_cfi.py
0030 file to keep the default in step with the contents of that file.
0031
0032 ---
0033
0034 All the default information is kept in three files:
0035
0036 FWCore/MessageService/src/HardwiredDefaults.cc
0037 FWCore/Utilities/interface/JobMode.h
0038 FWCore/MessageService/interface/MessageLoggerDefaults.h
0039 FWCore/MessageService/src/MessageLoggerDefaults.cc
0040
0041 If you are just changing the defaults for some mode, only HardwiredDefaults.cc
0042 needs to change. If you are creating a new mode, then the *.h and
0043 MessageLoggerDefaults.cc files will need modification.
0044
0045 -------------------------------------------------------------------------
0046
0047 EXAMPLE 1 -
0048 Change, in the existing default mode,
0049 the default summary threshold for the
0050 message statistics going to cerr from
0051 INFO to WARNING.
0052
0053 Observe that currently the PSet for the statistics destination
0054 is not in the cfg file; it shares cerr with the ordinary cerr
0055 output destination. So we will have to give the statistics destination
0056 its own name and direct its output to cerr. In _cfg.py language,
0057
0058 statistics = cms.untracked.vstring('cerr'),
0059
0060 becomes
0061
0062 statistics = cms.untracked.vstring('cerr_stats'),
0063 cerr_stats = cms.untracked.PSet(
0064 threshold = cms.untracked.string('WARNING'),
0065 output = cms.untracked.string('cerr')
0066 ),
0067
0068 Also note that the "default mode" that you would get by just saying cmsRun
0069 with no --mode= is mode="grid", which gives GridJobMode. You can see this
0070 in HardwiredDefaults.cc:
0071
0072 edm::JobMode
0073 MessageLoggerDefaults::
0074 mode(std::string const & jm)
0075 {
0076 if (jm == "") return GridJobMode; // no -mode option = grid
0077 if (jm == "grid") return GridJobMode;
0078 // and so forth
0079
0080 So the relevant code implementing the defaults for this mode is
0081
0082 MessageLoggerDefaults::hardwireGridJobMode()
0083
0084 Step 1:
0085
0086 Every list (destinations, statistics, categories) in the cfg file corresponds
0087 to a vector in the MessageLoggerDefaults class. We add items to the list by
0088 push_back. Thus, to change
0089 statistics = cms.untracked.vstring('cerr'),
0090 to
0091 statistics = cms.untracked.vstring('cerr_stats'),
0092 we change the code
0093 statistics.push_back ( "cerr" );
0094 to
0095 statistics.push_back ( "cerr_stats" );
0096
0097 You can see this line in the hardwireGridJobMode() method, about 7 lines
0098 after the start.
0099
0100 Step 2:
0101
0102 Every destination, including every statistics destination, can have a
0103 PSet with the options for that destination. The class that corresponds
0104 to that PSet is called Destination. The cerr statistics did not previously
0105 have such a PSet, so now we add one. Note that to avoid name clashes, we
0106 always enclose the code for setting up a Destination in braces. So far, we
0107 are adding (after the close brace for the section that started with
0108 Destination FrameworkJobReport):
0109
0110 { Destination cerr_stats; // PSet cerr
0111 // In step 3 we will fill in some configuration for this destination!
0112 destination["cerr_stats"] = cerr_stats;
0113 }
0114
0115 Note that event though this is a statistics destination, it goes into
0116 the map named destination.
0117
0118 Step 3:
0119
0120 Add (or change in an existing Destination) whatever options you need
0121 added or changed. In this example, we want to add:
0122 cerr_stats = cms.untracked.PSet(
0123 threshold = cms.untracked.string('WARNING'),
0124 output = cms.untracked.string('cerr')
0125 ),
0126 so this becomes
0127
0128 { Destination cerr_stats; // PSet cerr
0129 cerr_stats.threshold = "WARNING"; // string threshold = "INFO"
0130 cerr_stats.output = "cerr"; // string output = "cerr"
0131 destination["cerr_stats"] = cerr_stats;
0132 }
0133
0134 This is the code which is in the current (as of July 2008)
0135 hardwireGridJobMode() method, right near the end.
0136
0137 Step 4:
0138
0139 Build -- almost nothing needs recompilation -- and try it out.
0140
0141 -------------------------------------------------------------------------
0142
0143 EXAMPLE 2 -
0144 Add a new default mode, named infos,
0145 intended for release validators use.
0146 This should be the same as grid, but
0147 with statistics thresholds at INFO,
0148 and with the default limit for INFO
0149 at 5 instead of 0.
0150
0151 Step 0:
0152
0153 Create a new mode, identical to one of the existing modes:
0154
0155 a) In FWCore/Utilities/interface/JobMode.h, add a value to the JobMode enum
0156 with a name for this mode. I changed
0157 enum JobMode {
0158 GridJobMode
0159 , AnalysisJobMode
0160 , NilJobMode
0161 };
0162 to
0163 enum JobMode {
0164 GridJobMode
0165 , ReleaseValidationJobMode
0166 , AnalysisJobMode
0167 , NilJobMode
0168 };
0169
0170 b) In MessageService/src/MessageLoggerDefaults.h, add a method
0171 to set up that mode. In the section with comment
0172 // Modes with hardwired defaults
0173 I added the line
0174
0175 void hardwireReleaseValidationJobMode();
0176
0177 c) Still in MessageLoggerDefaults.h, ad a case to dispatch that method
0178 to the MessageLoggerDefaults ctor:
0179 switch (mode) {
0180 case GridJobMode:
0181 hardwireGridJobMode();
0182 break;
0183 case ReleaseValidationJobMode:
0184 hardwireReleaseValidationJobMode();
0185 break;
0186 ...
0187
0188 d) In MessageService/src/HardwiredDefaults.cc, make a copy of one of
0189 the hardwireXXXJobMode methods (I started from hardwireGridJobMode)
0190 and change the name (and the comment at the end) to the new one:
0191
0192 void MessageLoggerDefaults::
0193 hardwireReleaseValidationJobMode()
0194 {
0195 .
0196 .
0197 .
0198 } // hardwireReleaseValidationJobMode
0199
0200 e) Place the name of the new mode (infos) into the decision logic in the
0201 mode() method right at the beginning of HardwiredDefaults.cc:
0202 edm::JobMode
0203 MessageLoggerDefaults::
0204 mode(std::string const & jm)
0205 {
0206 if (jm == "") return GridJobMode;
0207 if (jm == "grid") return GridJobMode;
0208 if (jm == "infos") return ReleaseValidationJobMode;
0209 if (jm == "analysis") return AnalysisJobMode;
0210 ...
0211
0212 At this point, you have a new mode, IDENTICAL to the one you copied.
0213 It is a good idea to build (starting at FWCore or higher, because the
0214 JobModes.h file has changed) and try a cmsRun using the new mode.
0215
0216 All the remaining steps will concern the new method in HardiredDefaults.cc
0217 (in this example, MessageLoggerDefaults::hardwireReleaseValidationJobMode())
0218
0219 Step 1:
0220
0221 If a new destination (or change in a destination PSet name) has been done,
0222 add or change the item destinations or statistics list as in step 1 of
0223 Example 1.
0224
0225 Here there was nothing to do, since we still want everything going to cerr.
0226
0227 Step 2:
0228
0229 A new destination would require creating a new instance of the Destination
0230 class.
0231
0232 Here there was nothing to do, since we have no new destinations.
0233
0234
0235 Step 3:
0236
0237 Add (or change in an existing Destination) whatever options you need
0238 added or changed. In this example, we want to change to:
0239
0240 untracked PSet INFO = {
0241 untracked int32 limit = 5;
0242 }
0243
0244 where that 5 was zero earlier; that becomes
0245
0246 Category INFO_limits; // PSet INFO = { ... }
0247 INFO_limits.limit = 5; // int32 limit = 5
0248 cerr.sev["INFO"] = INFO_limits;
0249
0250 And we want the threshold for the statistics destination to go down to INFO
0251 rather than WARNING:
0252
0253 { Destination cerr_stats; // PSet cerr_stats
0254 cerr_stats.threshold = "INFO"; // string threshold = "INFO"
0255 cerr_stats.output = "cerr"; // string output = "cerr"
0256 destination["cerr_stats"] = cerr_stats;
0257 }
0258
0259 This is the code which is in the current (as of July 2008)
0260 hardwireReleaseValidationJobMode() method, right near the end.
0261
0262 Step 4:
0263
0264 Build -- almost nothing needs recompilation if you already tried out
0265 the new mode before changing it -- and try it out.
0266
