7 The logging library is normally configured using configuration strings.
9 In its most basic format, the configuration string consists of a comma
10 separated list of `CATEGORY=LEVEL` pairs, e.g.:
13 folly=INFO,folly.io.async=DBG2
16 A log level name can also be specified by itself to affect the root log
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)
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.
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
42 Basic Configuration Syntax
43 --------------------------
45 The basic configuration format is parsed using `parseLogConfig()`.
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.
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.
58 <config> ::= <category_configs> <handler_configs>
59 <category_configs> ::= <category_config>
60 | <category_config> "," <category_configs>
62 <handler_configs> ::= ";" <handler_config>
63 | ";" <handler_config> <handler_configs>
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>
73 <handler_config> ::= <handler_name> "=" <handler_type> ":" <handler_options>
74 | <handler_name> ":" <handler_options>
75 <handler_options> ::= "," <option_name> "=" <option_value> <handler_options>
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
86 <level> ::= <log_level_string>
88 <log_level_string> ::= any one of the strings accepted by logLevelToString()
91 ### Log Category Configuration
93 The log category configurations are a comma-separated list. Each element in
94 this list has the form
96 NAME=LEVEL:HANDLER1:HANDLER2
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 ".".
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.
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.
113 ### Log Handler Configuration
115 Each log handler configuration section takes the form
117 NAME=TYPE:OPTION1=VALUE1,OPTION2=VALUE2
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.
124 The log handler type may be omitted to update the settings of an existing log
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.
136 Example log configuration strings:
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.)
143 * `folly=INFO,folly.io=DBG2`
145 Sets the "folly" log category level to INFO, and the "folly.io" log
146 category level to DBG2.
148 * `folly=DBG2,folly.io:=INFO`
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
156 * `ERROR:stderr, folly=INFO; stderr=stream:stream=stderr`
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.
162 * `ERROR:x,folly=INFO:y;x=stream:stream=stderr;y=file:path=/tmp/y.log`
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.
170 * `ERROR:default:x; default=stream:stream=stderr; x=file:path=/tmp/x.log`
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.
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.
185 * `;default=stream:stream=stdout`
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
192 * `ERROR; stderr:async=true`
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()`.
201 JSON Configuration Syntax
202 -------------------------
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.
209 The input string is parsed using relaxed JSON parsing, allowing C and C++ style
210 comments, as well as trailing commas.
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.
216 ### Log Category Configuration
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
222 The value of each element in `categories` should also be a JSON object with the
227 This field is required. It should be a string or positive integer value
228 specifying the log level for this category.
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
236 This field is optional, and defaults to true if not present.
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.
242 ### Log Handler Configuration
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
248 The value of each element in `handlers` should also be a JSON object with the
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
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
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.
273 "foo": { "level": "INFO", "handlers": ["stderr"] },
274 "foo.only_fatal": { "level": "FATAL", "inherit": false }
282 "max_buffer_size": 4096000
290 Custom Configuration Mechanisms
291 -------------------------------
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.
298 You can also directly manipulate the log level and other settings on
299 `LogCategory` objects.
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