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_name> ":" <handler_options>
  75 <handler_options> ::= "," <option_name> "=" <option_value> <handler_options>
  76                     | <empty_string>
  77
  78 <catgory_name> ::= <atom>
  79 <handler_name> ::= <atom>
  80 <handler_type> ::= <atom>
  81 <option_name> ::= <atom>
  82 <option_value> ::= <atom>
  83 <atom> ::= any sequence of characters except ";", ",", "=", or ":",
  84            with leading and trailing whitespace ignored
  85
  86 <level> ::= <log_level_string>
  87           | <positive_integer>
  88 <log_level_string> ::= any one of the strings accepted by logLevelToString()
  89 ```
  90
  91 ### Log Category Configuration
  92
  93 The log category configurations are a comma-separated list.  Each element in
  94 this list has the form
  95
  96   NAME=LEVEL:HANDLER1:HANDLER2
  97
  98 The log category name and '=' sign can be omitted, in which case the setting
  99 applies to the root log category.  The root log category can also be
 100 explicitly named either using the empty string or the name ".".
 101
 102 The NAME and LEVEL can also be separated with ":=" instead of "=",
 103 which disables log level inheritance for this category.  This forces
 104 category's effective log level to be the exact level specified, even if its
 105 parent category has a more verbose level setting.
 106
 107 The log handler settings for a log category can be omitted, in which case
 108 the existing log handlers for this category will be left unchanged when
 109 updating the LoggerDB settings.  Specifying an empty log handler list (a
 110 trailing ':' with no log handlers following) will cause the log handler list
 111 for this category to be cleared instead.
 112
 113 ### Log Handler Configuration
 114
 115 Each log handler configuration section takes the form
 116
 117   NAME=TYPE:OPTION1=VALUE1,OPTION2=VALUE2
 118
 119 NAME specifies the log handler name, and TYPE specifies the log handler
 120 type.  A comma separated list of name=value options may follow the log
 121 handler name and type.  The option list will be passed to the
 122 LogHandlerFactory for the specified handler type.
 123
 124 The log handler type may be omitted to update the settings of an existing log
 125 handler object:
 126
 127   NAME:OPTION1=VALUE1
 128
 129 A log handler with this name must already exist.  Options specified in the
 130 configuration will be updated with their new values, and any option names not
 131 mentioned will be left unchanged.
 132
 133
 134 ### Examples
 135
 136 Example log configuration strings:
 137
 138 * `ERROR`
 139
 140   Sets the root log category level to ERR.  (Note that `ERROR` is allowed in
 141   configuration strings as an alias for the `LogLevel::ERR` value.)
 142
 143 * `folly=INFO,folly.io=DBG2`
 144
 145   Sets the "folly" log category level to INFO, and the "folly.io" log
 146   category level to DBG2.
 147
 148 * `folly=DBG2,folly.io:=INFO`
 149
 150   Sets the "folly" log category level to DBG2, and the "folly.io" log
 151   category level to INFO, and prevent it from inheriting its effective log
 152   level from its parent category.  DBG2 log messages sent to "folly.io" will
 153   therefore be discarded, even though they are enabled for one of its parent
 154   categories.
 155
 156 * `ERROR:stderr, folly=INFO; stderr=stream:stream=stderr`
 157
 158   Sets the root log category level to ERROR, and sets its handler list to
 159   use the "stderr" handler.  Sets the folly log level to INFO.  Defines
 160   a log handler named "stderr" which writes to stderr.
 161
 162 * `ERROR:x,folly=INFO:y;x=stream:stream=stderr;y=file:path=/tmp/y.log`
 163
 164   Defines two log handlers: "x" which writes to stderr and "y" which
 165   writes to the file /tmp/y.log
 166   Sets the root log catgory level to ERROR, and configures it to use the
 167   "x" handler.  Sets the log level for the "folly" category to INFO and
 168   configures it to use the "y" handler.
 169
 170 * `ERROR:default:x; default=stream:stream=stderr; x=file:path=/tmp/x.log`
 171
 172   Defines two log handlers: "default" which writes to stderr and "x" which
 173   writes to the file /tmp/x.log
 174   Sets the root log catgory level to ERROR, and configures it to use both
 175   the "default" and "x" handlers.
 176
 177 * `ERROR:`
 178
 179   Sets the root log category level to ERR, and removes any log handlers
 180   configured for it.  Explicitly specifying an empty list of handlers (with
 181   a ':' followed by no handlers) will update the handlers for this category
 182   to the empty list.  Not specifying handler information at all (no ':')
 183   will leave any pre-existing handlers as-is.
 184
 185 * `;default=stream:stream=stdout`
 186
 187   Does not change any log category settings, and defines a "default" handler
 188   that writes to stdout.  This format is useful to update log handler settings
 189   if the "default" handler already exists and is attached to existing log
 190   categories.
 191
 192 * `ERROR; stderr:async=true`
 193
 194   Sets the root log category level to ERR, and sets the "async" property to
 195   true on the "stderr" handler.  A log handler named "stderr" must already
 196   exist.  Therefore this configuration string is only valid to use with
 197   `LoggerDB::updateConfig()`, and cannot be used with
 198   `LoggerDB::resetConfig()`.
 199
 200
 201 JSON Configuration Syntax
 202 -------------------------
 203
 204 The `parseLogConfig()` function, which parses the basic configuration string
 205 syntax, will also accept a JSON object string as input.  However, you can also
 206 use `parseLogConfigJson()` to explicitly parse the input as JSON, and not
 207 accept the basic configuration string syntax.
 208
 209 The input string is parsed using relaxed JSON parsing, allowing C and C++ style
 210 comments, as well as trailing commas.
 211
 212 The JSON configuration string must be a JSON object data type, with two
 213 optional members: `categories` and `handlers`.  Any additional members besides
 214 these two are ignored.
 215
 216 ### Log Category Configuration
 217
 218 If present, the `categories` member of the top-level object should be a JSON
 219 object mapping log category names to configuration settings for that log
 220 category.
 221
 222 The value of each element in `categories` should also be a JSON object with the
 223 following fields:
 224
 225 * `level`
 226
 227   This field is required.  It should be a string or positive integer value
 228   specifying the log level for this category.
 229
 230 * `inherit`
 231
 232   This should be a boolean value indicating if this category should inherit its
 233   effective log level from its parent category if its parent has a more verbose
 234   log level setting.
 235
 236   This field is optional, and defaults to true if not present.
 237
 238 Alternatively, the value for a log category may be a plain string or integer
 239 instead of a JSON object, in which case case the string or integer is treated
 240 as the log level for that category, with the inherit setting enabled.
 241
 242 ### Log Handler Configuration
 243
 244 If present, the `handlers` member of the top-level object should be a JSON
 245 object mapping log handler names to configuration settings for that log
 246 handler.
 247
 248 The value of each element in `handlers` should also be a JSON object with the
 249 following fields:
 250
 251 * `type`
 252
 253   This field should be a string containing the name of the log handler type.
 254   This type name must correspond to `LogHandlerFactory` type registered with
 255   the `LoggerDB`.
 256
 257   If this field is not present then this configuration will be used to update
 258   an existing log handler.  A log handler with this name must already exist.
 259   The values from the `options` field will be merged into the existing log
 260   handler options.
 261
 262 * `options`
 263
 264   This field is optional.  If present, it should be a JSON object containing
 265   string-to-string mappings to be passed to the `LogHandlerFactory` for
 266   constructing this log handler.
 267
 268 ### Example
 269
 270 ```javascript
 271 {
 272   "categories": {
 273     "foo": { "level": "INFO", "handlers": ["stderr"] },
 274     "foo.only_fatal": { "level": "FATAL", "inherit": false }
 275   }
 276   "handlers": {
 277     "stderr": {
 278       "type": "stream",
 279       "options": {
 280         "stream": "stderr",
 281         "async": true,
 282         "max_buffer_size": 4096000
 283       }
 284     }
 285   }
 286 }
 287 ```
 288
 289
 290 Custom Configuration Mechanisms
 291 -------------------------------
 292
 293 Internally the the `LogConfig` class represents configuration settings for the
 294 folly logging library.  Users of the logging library can also programmatically
 295 construct their own `LogConfig` objects and use the `LoggerDB::updateConfig()`
 296 and `LoggerDB::resetConfig()` APIs to apply the configuration changes.
 297
 298 You can also directly manipulate the log level and other settings on
 299 `LogCategory` objects.
 300
 301 While it is possible to also manually create new `LogHandler` objects, it is
 302 generally preferred to do this using the `LoggerDB::updateConfig()` and
 303 `LoggerDB::resetConfig()` APIs.  If you manually create a new `LogHandler` and
 304 directly attach it to some categories the `LoggerDB::getConfig()` call will not
 305 be able to return complete information for your manually created log handler,
 306 since it does not have a name or handler type that can be included in the
 307 configuration.