folly/experimental/logging/docs/Config.md

   1 Logging Configuration
   2 =====================
   3
   4 Overview
   5 --------
   6
   7 The logging library is normally configured using configuration strings.
   8
   9 In its most basic format, the configuration string consists of a comma
  10 separated list of `CATEGORY=LEVEL` pairs, e.g.:
  11
  12 ```
  13 folly=INFO,folly.io.async=DBG2
  14 ```
  15
  16 A log level name can also be specified by itself to affect the root log
  17 category:
  18
  19 ```
  20 WARN
  21 ```
  22
  23 These are the two forms that users will probably use most often for customizing
  24 log levels via command line arguments.  Additional settings, including log
  25 handler settings, can also be included.  The syntax is documented more
  26 completely in the [Basic Configuration Syntax](#basic-configuration-syntax)
  27 section.
  28
  29 Log configuration can also be specified using JSON as well.  If the log
  30 configuration string starts with a leading `{` character (optionally after
  31 leading whitespace), it is parsed as a JSON object.  The JSON configuration
  32 format is documented in the
  33 [JSON Configuration Syntax](#json-configuration-syntax) section.
  34
  35 In general the basic configuration syntax is convenient for controlling log
  36 levels, and making minor log handler setting changes (such as controlling if
  37 logging goes to stdout or stderr, and whether it is logged asynchronously or
  38 not).  However the JSON format is easier to use to describe more complicated
  39 settings.
  40
  41
  42 Basic Configuration Syntax
  43 --------------------------
  44
  45 The basic configuration format is parsed using `parseLogConfig()`.
  46
  47 The basic format string is separated with semicolons.  Everything up to the
  48 first semicolon specifies LogCategory configurations.  Each remaining
  49 semicolon-separated section defines a LogHandler configuration.
  50
  51 To keep the basic format simple, it does not support any form of character
  52 escape sequences.  If you need to define a log category whose name includes a
  53 special character like a comma or semicolon use the JSON format instead.
  54
  55 ### Grammar Overview
  56
  57 ```
  58 <config> ::= <category_configs> <handler_configs>
  59 <category_configs> ::= <category_config>
  60                      | <category_config> "," <category_configs>
  61                      | <empty_string>
  62 <handler_configs> ::= ";" <handler_config>
  63                     | ";" <handler_config> <handler_configs>
  64                     | <empty_string>
  65
  66 <category_config> ::= <cat_level_config> <handler_list>
  67 <cat_level_config> ::= <level>
  68                      | <catgory_name> "=" <level>
  69                      | <catgory_name> ":=" <level>
  70 <handler_list> ::= ":" <handler_name> <handler_list>
  71                  | <empty_string>
  72
  73 <handler_config> ::= <handler_name> "=" <handler_type> <handler_options>
  74 <handler_options> ::= "," <option_name> "=" <option_value> <handler_options>
  75                     | <empty_string>
  76
  77 <catgory_name> ::= <atom>
  78 <handler_name> ::= <atom>
  79 <handler_type> ::= <atom>
  80 <option_name> ::= <atom>
  81 <option_value> ::= <atom>
  82 <atom> ::= any sequence of characters except ";", ",", "=", or ":",
  83            with leading and trailing whitespace ignored
  84
  85 <level> ::= <log_level_string>
  86           | <positive_integer>
  87 <log_level_string> ::= any one of the strings accepted by logLevelToString()
  88 ```
  89
  90 ### Log Category Configuration
  91
  92 The log category configurations are a comma-separated list.  Each element in
  93 this list has the form
  94
  95   NAME=LEVEL:HANDLER1:HANDLER2
  96
  97 The log category name and '=' sign can be omitted, in which case the setting
  98 applies to the root log category.  The root log category can also be
  99 explicitly named either using the empty string or the name ".".
 100
 101 The NAME and LEVEL can also be separated with ":=" instead of "=",
 102 which disables log level inheritance for this category.  This forces
 103 category's effective log level to be the exact level specified, even if its
 104 parent category has a more verbose level setting.
 105
 106 The log handler settings for a log category can be omitted, in which case
 107 the existing log handlers for this category will be left unchanged when
 108 updating the LoggerDB settings.  Specifying an empty log handler list (a
 109 trailing ':' with no log handlers following) will cause the log handler list
 110 for this category to be cleared instead.
 111
 112 ### Log Handler Configuration
 113
 114 Each log handler configuration section takes the form
 115
 116   NAME=TYPE,OPTION1=VALUE1,OPTION2=VALUE2
 117
 118 NAME specifies the log handler name, and TYPE specifies the log handler
 119 type.  A comma separated list of name=value options may follow the log
 120 handler name and type.  The option list will be passed to the
 121 LogHandlerFactory for the specified handler type.
 122
 123
 124 ### Examples
 125
 126 Example log configuration strings:
 127
 128 * `ERROR`
 129
 130   Sets the root log category level to ERR.  (Note that `ERROR` is allowed in
 131   configuration strings as an alias for the `LogLevel::ERR` value.)
 132
 133 * `folly=INFO,folly.io=DBG2`
 134
 135   Sets the "folly" log category level to INFO, and the "folly.io" log
 136   category level to DBG2.
 137
 138 * `folly=DBG2,folly.io:=INFO`
 139
 140   Sets the "folly" log category level to DBG2, and the "folly.io" log
 141   category level to INFO, and prevent it from inheriting its effective log
 142   level from its parent category.  DBG2 log messages sent to "folly.io" will
 143   therefore be discarded, even though they are enabled for one of its parent
 144   categories.
 145
 146 * `ERROR:stderr, folly=INFO; stderr=file,stream=stderr`
 147
 148   Sets the root log category level to ERROR, and sets its handler list to
 149   use the "stderr" handler.  Sets the folly log level to INFO.  Defines
 150   a log handler named "stderr" which writes to stderr.
 151
 152 * `ERROR:default,folly=INFO:x;default=file,stream=stderr;x=file,path=/tmp/x.log`
 153
 154   Defines two log handlers: "default" which writes to stderr and "x" which
 155   writes to the file /tmp/x.log
 156   Sets the root log catgory level to ERROR, and configures it to use the
 157   "default" handler.  Sets the log level for the "folly" category to INFO and
 158   configures it to use the "x" handler.
 159
 160 * `ERROR:default:x; default=file,stream=stderr; x=file,path=/tmp/x.log`
 161
 162   Defines two log handlers: "default" which writes to stderr and "x" which
 163   writes to the file /tmp/x.log
 164   Sets the root log catgory level to ERROR, and configures it to use both
 165   the "default" and "x" handlers.
 166
 167 * `ERROR:`
 168
 169   Sets the root log category level to ERR, and removes any log handlers
 170   configured for it.  Explicitly specifying an empty list of handlers (with
 171   a ':' followed by no handlers) will update the handlers for this category
 172   to the empty list.  Not specifying handler information at all (no ':')
 173   will leave any pre-existing handlers as-is.
 174
 175 * `;default=file,stream=stdout`
 176
 177   Does not change any log category settings, and defines a "default" handler
 178   that writes to stdout.  This format is useful to update log handler settings
 179   if the "default" handler already exists and is attached to existing log
 180   categories.
 181
 182
 183 JSON Configuration Syntax
 184 -------------------------
 185
 186 The `parseLogConfig()` function, which parses the basic configuration string
 187 syntax, will also accept a JSON object string as input.  However, you can also
 188 use `parseLogConfigJson()` to explicitly parse the input as JSON, and not
 189 accept the basic configuration string syntax.
 190
 191 The input string is parsed using relaxed JSON parsing, allowing C and C++ style
 192 comments, as well as trailing commas.
 193
 194 The JSON configuration string must be a JSON object data type, with two
 195 optional members: `categories` and `handlers`.  Any additional members besides
 196 these two are ignored.
 197
 198 ### Log Category Configuration
 199
 200 If present, the `categories` member of the top-level object should be a JSON
 201 object mapping log category names to configuration settings for that log
 202 category.
 203
 204 The value of each element in `categories` should also be a JSON object with the
 205 following fields:
 206
 207 * `level`
 208
 209   This field is required.  It should be a string or positive integer value
 210   specifying the log level for this category.
 211
 212 * `inherit`
 213
 214   This should be a boolean value indicating if this category should inherit its
 215   effective log level from its parent category if its parent has a more verbose
 216   log level setting.
 217
 218   This field is optional, and defaults to true if not present.
 219
 220 Alternatively, the value for a log category may be a plain string or integer
 221 instead of a JSON object, in which case case the string or integer is treated
 222 as the log level for that category, with the inherit setting enabled.
 223
 224 ### Log Handler Configuration
 225
 226 If present, the `handlers` member of the top-level object should be a JSON
 227 object mapping log handler names to configuration settings for that log
 228 handler.
 229
 230 The value of each element in `handlers` should also be a JSON object with the
 231 following fields:
 232
 233 * `type`
 234
 235   This field is required.  It should be a string containing the name of the log
 236   handler type.  This type name must correspond to `LogHandlerFactory` type
 237   registered with the `LoggerDB`.
 238
 239 * `options`
 240
 241   This field is optional.  If present, it should be a JSON object containing
 242   string-to-string mappings to be passed to the `LogHandlerFactory` for
 243   constructing this log handler.
 244
 245 ### Example
 246
 247 ```javascript
 248 {
 249   "categories": {
 250     "foo": { "level": "INFO", "handlers": ["stderr"] },
 251     "foo.only_fatal": { "level": "FATAL", "inherit": false }
 252   }
 253   "handlers": {
 254     "stderr": {
 255       "type": "file",
 256       "options": {
 257         "stream": "stderr",
 258         "async": true,
 259         "max_buffer_size": 4096000
 260       }
 261     }
 262   }
 263 }
 264 ```
 265
 266
 267 Custom Configuration Mechanisms
 268 -------------------------------
 269
 270 Internally the the `LogConfig` class represents configuration settings for the
 271 folly logging library.  Users of the logging library can also programmatically
 272 construct their own `LogConfig` objects and use the `LoggerDB::updateConfig()`
 273 and `LoggerDB::resetConfig()` APIs to apply the configuration changes.
 274
 275 You can also directly manipulate the log level and other settings on
 276 `LogCategory` objects.
 277
 278 While it is possible to also manually create new `LogHandler` objects, it is
 279 generally preferred to do this using the `LoggerDB::updateConfig()` and
 280 `LoggerDB::resetConfig()` APIs.  If you manually create a new `LogHandler` and
 281 directly attach it to some categories the `LoggerDB::getConfig()` call will not
 282 be able to return complete information for your manually created log handler,
 283 since it does not have a name or handler type that can be included in the
 284 configuration.