LogBox is the core framework you need to instantiate in order to work with logging in your application. You have to instantiate it with a LogBoxConfig object that will hold your logging configurations. After the library is instantiated and configured you can ask from it a named Logger object so you can start logging or tracing messages.

You have two ways to use LogBox:

• Standalone Framework

• Within a ColdBox application

If you have downloaded LogBox as a standalone framework, then the initial namespace for the core is logbox.system. This allows you to use logbox as a standalone framework that is integrated into your proprietary application.

The ColdBox Framework already has an instance of LogBox created for you in every application and it is stored in the main application controller: controller.getLogBox(). The namespace within the ColdBox framework is coldbox.system.

Logbox

Logger Category InheritanceSecurity LevelsDynamic Appenders

LogBox has four main components:

1. LogBox

2. Logger

3. Appenders

4. Layouts.

These four (4) components work in unison to deliver the logging and tracing of messages and to control how they are logged. You will mostly interact with the Logger component as it will send your statements to the Appenders you have configured. Users can extend LogBox and build their own appenders and layouts.

The layout component defines the format of the message to store in an appender repository. Be default, each appender already has a pre-defined message format. However, if you do not like the format of the message you can easily change it by creating your own layout component and registering it with the appender. You can do this in the configuration object when you add appenders:

Note: Not all appenders use a layout object (e.g. the DBAppender).

//add a FileAppender with my own formatting
props = { filePath='/logs', fileName='Test' };
config.appender(
    name='Fileapp',
    class="logbox.system.logging.appenders.FileAppender",
    properties=props,
    layout="model.logging.MyFileLayout"
);

So to create your very own layout object, you just need to extend the LogBox abstract layout object: logbox.system.logging.Layout and implement the format() method.

We have a convention for our category names where each category name uses dot-notation according to the components path. Using a class-path convention for our category names allows one to pseudo-inherit for logging levels and appenders! The following example should help clarify this concept.

The overall premise is that when you request a logger with a category name LogBox will search for it's configuration. If LogBox does not find a configuration for the category name it will try to locate its closest ancestor for logging levels and appenders. If LogBox cannot find an ancestor the message will be logged using the root logger information. For example, let's say we define some appenders like this:

// Appenders
config.appender(
  name="console",
  class="logbox.system.logging.appenders.ConsoleAppender"
);
config.appender(
  name="file",
  class="logbox.system.logging.appenders.FileAppender",
  properties={ filePath="/logs" }
)

And some categories like this:

// Explicit Categories
config.category(
  name="coldbox.system",
  levelMin=config.logLevels.INFO,
  appenders="console"
);

// Implicit Categories
config.error(
  "coldbox.system.plugins"
);
// same as
config.cateogry(
  name="coldbox.system.plugins",
  levelMax="ERROR"
);

Then, let's say we request the following logger objects and logged some info:

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" );

Information All example code snippets are using a getLogger( "categoryname" ) call instead of our preferred approach of getLogger( this ) because we want to showcase which category we are talking about. Please take this into consideration.

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 it's inherited category. So the info() message will be ignored, and the error() message will be sent to both the FileAppender and the ConsoleAppender!

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 INFO level and ONLY the console appender. So the messages that get logged is the logger.info() and the logger.debug() message and they will be sent to the console appender.

These examples should give you insight into category inheritance and the power they provide. You can easily turn toggle logging for entire packages with a single category definition. However, this is great only if you follow the dot notation conventions. Below is a sample generic chart sample:

Each logger object has several methods that you can use in order to interact with the logger's appenders. You can add, remove, clear or list the appenders on a specific logger instance. Below are the methods you can use in the logger class to interact with appenders:

So you can easily add/remove/check the appenders on any logger at any time.

//Add your own appender at runtime
jms = createObject( "component", "com.appender.JMSAppender" ).init( "JMSAppender", properties );
logger.addAppender( jms );

//log a message to all appenders and to my jms appender:
logger.fatal( "I FAILED MAN!" );

//remove it
logger.removeAppender( "JMSAppender" );

An appender is an object that LogBox uses to log statements to a destination repository. All appenders act as destinations that can include: databases, JMS, files, consoles, sockets, etc. The appender has the responsibility of taking the logged message and persisting the message or sending the message to an external service. LogBox comes bundled with the following appenders that can be found in the package coldbox.system.logging.appenders:

Asynchronous Appenders

You may wish your logs to be asynchronous. You can do so by passing an async property in your configuration. ( This happens at the logger level and is available to all appenders out of the box, even ones that you create yourself!

// Any appender can be asynchronous!
dbDebugger = {
    class="logbox.system.logging.appenders.DBAppender",
    properties={
        dsn="blog",
        table="logs",
        autocreate=true,
        textDBType="NCLOB",
        async=true
    }
}

Configuration

You can configure LogBox to use one or all of these appenders at any point in time. You can even register as many instances of any appender by defining a unique name for each. Here are examples of how one can configure appenders programmatically or via the simple configuration CFC:

Programmatic Approach

// Adding appenders
props = {
    filePath=expandPath( "/logbox/testing/cases/logging/tmp" ),
    autoExpand=false,
    fileMaxArchives=1,
    fileMaxSize=3000,
    async=true
};

config.appender(
    name="MyAsyncFile",
    class="logbox.system.logging.appenders.RollingFileAppender",
    properties=props
);

// Socket
props = { host="localhost", port="444", timeout="3", persistConnection=false };
config.appender(
    name="SocketAppender",
    class="logbox.system.logging.appenders.SocketAppender",
    properties=props
);

Configuration CFC approach

function configure(){

    logBox = {
        // Register Appenders
        appenders = {
            MyAsyncFile = {
                class="logbox.system.logging.appenders.RollingFileAppender",
                properties={
                    filePath=expandPath( "/logbox/testing/cases/logging/tmp" ),
                    autoExpand=false,
                    fileMaxArchives=1,
                    fileMaxSize=3000,
                    async=true
                }
            },

            SocketAppender = {
                class="logbox.system.logging.appenders.SocketAppender",
                properties={
                    host="localhost",
                    port="444",
                    timeout="3",
                    persistConnection=false
                }
            }
        }
    };

}

Another feature of a LogBox appender is that you can extend them or create new ones simply by leveraging the LogBox API. To customize LogBox appenders for your own unique needs you would simply extend the core appender class: coldbox.system.logging.AbstractAppender and implementing the init() and logMessage() methods. Extending LogBox will be reviewed in greater detail over the next few sections.