proxygen
proxygen/folly/folly/logging/docs/LogCategories.md
Go to the documentation of this file.
1 # Log Categories
2 
3 Each log message is logged to a specific log category.
4 
5 Log categories have a level setting that controls what log messages should be
6 enabled for this category, as well as a list of log handlers that control what
7 should be done with enabled log messages.
8 
9 # Log Category Hierarchy
10 
11 Log categories are arranged in a hierarchy. Each log category except for the
12 root has a parent category, and they may have zero or more children categories.
13 
14 The log category hierarchy is determined by category names: the `.`
15 character acts as a separator in category names. For example, the category
16 `spacesim` is the parent of the category `spacesim.ships`. The root category
17 can be referred to either as `.` or as the empty string.
18 
19 One recommended option for choosing log category names is to follow the source
20 code directory structure. For example, a partial view of the log category
21 hierarchy for a space simulator project might look something like:
22 
23 ```
24 . --- spacesim --- ships --- corvette -- cpp
25  \ \ \- h
26  | \- cruiser -- cpp
27  | \- h
28  |
29  \- actors --- player -- cpp
30  \ \- h
31  \- ai --- enemy -- cpp
32  \- h
33 ```
34 
35 The `XLOG()` macro automatically selects the log category to use based on the
36 source file path.
37 
38 # Log Level Propagation
39 
40 Log level settings automatically propagates downward from a particular log
41 category to its children.
42 
43 If the log verbosity is increased on a particular log category (by lowering the
44 minimum enabled log level) , all of its children also inherit that increased
45 log verbosity by default. For instance, setting the log level to `INFO` on
46 `spacesim.ships` will automatically enable `INFO` and higher log messages on
47 the `spacesim.ships` category as well as children categories such as
48 `spacesim.ships.corvette`, `spacesim.ships.fighter`, etc. This makes it easily
49 possible to control the log verbosity of entire sections of the code base at
50 once.
51 
52 Log level propagation can be disabled on specific categories by turning off the
53 `inherit` setting for that category. For instance, disabling the `inherit`
54 setting on the `spacesim.ships.cruiser` category will prevent it form
55 inheriting increased log level verbosity from its parent `spacesim.ships`
56 category (or indirectly inheriting settings from `spacesim` or the root
57 category). This makes it possible to turn down the verbosity for specific
58 categories even if when a larger category they belong to does have a higher
59 verbosity setting.
60 
61 # Log Message Propagation
62 
63 Logged messages propagate upwards through the log category hierarchy.
64 
65 For instance, a message logged to `spacesim.ships.corvette.cpp` will first be
66 sent to any `LogHandler` objects configured on `spacesim.ship.corvette.cpp`,
67 then to the handlers for `spacesim.ships.corvette`, then `spacesim.ships`, then
68 to `spacesim`, and finally to the handlers for the root log category.
69 
70 Due to this behavior, if you install a `LogHandler` on the root log category it
71 will automatically receive all messages logged to any category. Installing
72 `LogHandler` objects on sub-categories allows you to perform handling only for
73 specific category messages. `LogHandler` objects receive the full `LogMessage`
74 object, and can perform further filtering based on the log level or other
75 message properties if desired.
76 
77 The [Log Handler](LogHandlers.md) documentation provides additional details
78 about log handler behavior.