The overall premise is that when you request a logger with a category name, LogBox will search for its configuration (logging levels and appenders), if it does not find it it will try to locate its closest ancestor for logging levels and appenders, if it cannot find one, the it will rely on the root logger information (A default logger we ALWAYS define). Let's say we define some categories like this:
// Configured Appenders: FileAppender, ConsoleAppender, TwitterAppender config.category(name="coldbox.system",levelMin=config.logLevels.DEBUG,appenders="console"); config.error("coldbox.system.plugins");Then let's say we request the following logger objects:
logger = logBox.getLogger("coldbox.system.plugins.BeanFactory"); logger.info("hello info"); logger.error("wow and error occurred"); logger = logBox.getLogger("coldbox.system.interceptors.SES"); logger.info("hello info"); logger.debug("a cool debug message");Below is a chart representation of the category inheritance in our example:
|category||configured levels||assigned levels||appenders|
|coldbox.system.interceptors.SES||NONE||DEBUG-TRACE from coldbox.system||console from coldbox.system|
|coldbox.system.plugins.BeanFactory||NONE||ERROR from coldbox.system.plugins||*|
Since we requested the category: coldbox.system.plugins.BeanFactory, LogBox tries to locate it, but it has not been defined, so it takes off the last item in the category name. Now it will search for a category of: coldbox.system.plugins via pseudo-inheritance. However, now coldbox.system.plugins HAS been found and it has been configured to only listen to error messages. Therefore, the coldbox.system.plugins.BeanFactory logger can ONLY log error messages according to its inherited category. So the info() message will be ignored.
The second logger is called coldbox.system.interceptors.SES, LogBox tries to match a category but fails, so it now searches for a logger called coldbox.system.interceptors. It still cannot find it so it continues up the package chain and finds the coldbox.system logger which has been set with a minimum of DEBUG level and ONLY the console appender. So the only message that get's logged is the logger.debug() message and into the console appender.
I hope these examples give you insight into category inheritance and the power it can give you because you can easily turn on/off logging for entire packages with one single category definition. However, this is great only if you follow the dot notation conventions. Below is a sample generic chart sample:
|category||configured levels||assigned levels|
|x||NONE||FATAL-TRACE from root|
|x.y.z||NONE||INFO from x.y|