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_options> ::= "," <option_name> "=" <option_value> <handler_options>
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
85 <level> ::= <log_level_string>
87 <log_level_string> ::= any one of the strings accepted by logLevelToString()
90 ### Log Category Configuration
92 The log category configurations are a comma-separated list. Each element in
93 this list has the form
95 NAME=LEVEL:HANDLER1:HANDLER2
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 ".".
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.
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.
112 ### Log Handler Configuration
114 Each log handler configuration section takes the form
116 NAME=TYPE,OPTION1=VALUE1,OPTION2=VALUE2
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.
126 Example log configuration strings:
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.)
133 * `folly=INFO,folly.io=DBG2`
135 Sets the "folly" log category level to INFO, and the "folly.io" log
136 category level to DBG2.
138 * `folly=DBG2,folly.io:=INFO`
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
146 * `ERROR:stderr, folly=INFO; stderr=file,stream=stderr`
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.
152 * `ERROR:default,folly=INFO:x;default=file,stream=stderr;x=file,path=/tmp/x.log`
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.
160 * `ERROR:default:x; default=file,stream=stderr; x=file,path=/tmp/x.log`
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.
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.
175 * `;default=file,stream=stdout`
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
183 JSON Configuration Syntax
184 -------------------------
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.
191 The input string is parsed using relaxed JSON parsing, allowing C and C++ style
192 comments, as well as trailing commas.
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.
198 ### Log Category Configuration
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
204 The value of each element in `categories` should also be a JSON object with the
209 This field is required. It should be a string or positive integer value
210 specifying the log level for this category.
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
218 This field is optional, and defaults to true if not present.
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.
224 ### Log Handler Configuration
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
230 The value of each element in `handlers` should also be a JSON object with the
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`.
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.
250 "foo": { "level": "INFO", "handlers": ["stderr"] },
251 "foo.only_fatal": { "level": "FATAL", "inherit": false }
259 "max_buffer_size": 4096000
267 Custom Configuration Mechanisms
268 -------------------------------
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.
275 You can also directly manipulate the log level and other settings on
276 `LogCategory` objects.
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