Improvements

There are two major improvements we did with LogBox in this release:

1) The file locking operations on file appenders have been streamlined to avoid high i/o operations.

2) The console appender uses an asynchronous streaming technique which makes it extremely efficient and fast.

Release Notes

New Feature

Improvement

 __        ______     _______ .______     ______   ___   ___ 
|  |      /  __  \   /  _____||   _  \   /  __  \  \  \ /  / 
|  |     |  |  |  | |  |  __  |  |_)  | |  |  |  |  \  V  /  
|  |     |  |  |  | |  | |_ | |   _  <  |  |  |  |   >   <   
|  `----.|  `--'  | |  |__| | |  |_)  | |  `--'  |  /  .  \  
|_______| \______/   \______| |______/   \______/  /__/ \__\

LogBox Manual - Version 5.0.0

LogBox is a standalone enterprise ColdFusion (CFML) logging library designed to give you flexibility, simplicity and power when logging or tracing is needed in your applications. LogBox is also part of the ColdBox Platform suite of services and libraries and allows you to easily build upon it's logging framework in order to meet any logging or reporting needs your applications has. LogBox surpasses ColdFusion's very basic cflog tag. LogBox allows you to create multiple destinations for your loggings and even configure multiple destinations or change them at runtime.

Versioning

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

• Copyright by Ortus Solutions, Corp

• ColdBox is a registered trademark by Ortus Solutions, Corp

Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

Discussion & Help

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by **faith**, we have peace with God through our Lord Jesus Christ: By whom also we have access by **faith** into this **grace** wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

 __        ______     _______ .______     ______   ___   ___ 
|  |      /  __  \   /  _____||   _  \   /  __  \  \  \ /  / 
|  |     |  |  |  | |  |  __  |  |_)  | |  |  |  |  \  V  /  
|  |     |  |  |  | |  | |_ | |   _  <  |  |  |  |   >   <   
|  `----.|  `--'  | |  |__| | |  |_)  | |  `--'  |  /  .  \  
|_______| \______/   \______| |______/   \______/  /__/ \__\

LogBox Manual - Version 5.x

LogBox is a standalone enterprise ColdFusion (CFML) logging library designed to give you flexibility, simplicity and power when logging or tracing is needed in your applications. LogBox is also part of the ColdBox Platform suite of services and libraries and allows you to easily build upon it's logging framework in order to meet any logging or reporting needs your applications has. LogBox surpasses ColdFusion's very basic cflog tag. LogBox allows you to create multiple destinations for your loggings and even configure multiple destinations or change them at runtime.

Versioning

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

• Copyright by Ortus Solutions, Corp

• ColdBox is a registered trademark by Ortus Solutions, Corp

Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.

Discussion & Help

Reporting a Bug

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, its not for you.

"Therefore being justified by **faith**, we have peace with God through our Lord Jesus Christ: By whom also we have access by **faith** into this **grace** wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

Introduction

LogBox 2.0.0 is a major release, mostly aligned to support our ColdBox 4 release.

Release Notes

Bug

Improvement

New Feature

This release is part of the ColdBox 4.2.0 update and contains the following updates:

Improvement

This is a major release and a major rewrite of the entire framework to modern CFML, optimizations and script modes.

We have also improved all appenders for performance and reliability. Especially, the file logging facilities have been drastically improved. The new file based appenders now rely on a queuing mechanism and listener watcher threads that stream content to the file repositories.

Release Notes

Improvements

• LogBox can handle the inserting of logging and/or tracing statements in your application with a simple to use API while providing you the ability to manage logging behavior outside of your application code.

• You can configure LogBox via a programmatic configuration file (cfc)

• LogBox categorizes your logging and/or tracing statements according to user-defined categories that can be configured at runtime or pre-runtime. All of these categorizations can have their own logging level ranges (such as debug or info) and even their own destination points or what we refer to as LogBox Appenders (such as Console).

• LogBox Appenders are the destination points you configure for your logging and/or tracing statements. LogBox also offers a basic extensible API so you can build and extend upon the Appender framework according to your unique logging or tracing needs. This gives you complete control and flexibility of how to expand LogBox without reinventing the wheel. Some appenders included in LogBox can log to the following destinations: File, Database, Sockets, Email, ColdFusion logging, System Console, and much more.

• LogBox facilitates the creation of your very own customized message formats via Layouts. You can create a Layout component that can be configured in to ANY LogBox appender so it can spit out your very own customized messages.

• LogBox can be instantiated as many times as you want and used as many times as you like in a single application. There are no restrictions upon its usage.

• LogBox allows for category inheritance according to component and package conventions.

Improvements

• The majority of code examples in this book are done in cfscript.

• All ColdFusion examples designed to run on the open soure Railo Platform or Adobe ColdFusion 9.0.2+

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc. Railo is a trademark and copyright of Railo Technologies, GmbH.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.

Contributing

Charitable Proceeds

Shalom Children's Home

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

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.

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.

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:

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.

Most applications require logging and tracing capabilities. One can usually use ColdFusion's standard cflog or cftrace tags but you can reach a limitation very fast.

• What if you needed to log only certain severity levels for a particular CFC or piece of code?

• What if you needed that severity to advise you via SMS or Twitter (yes Twitter)?

• What if you wanted to turn it off easily or reconfigure your logging levels?

You would have to build all of these advising and logging capabilities yourself. Also, inserting log statements is tedious, time consuming and frequently pollutes your real code. You can understand the pain and complexity required to properly deal with these situations. These reasons (and more) are why the ColdBox team has invested in building LogBox.

LogBox can be downloaded as a standalone framework or it is included with the latest ColdBox Platform release. The main difference between both versions is the instantiation and usage namespace, the rest is the same.

The best way to install LogBox is using CommandBox CLI and package manager.

System Requirements

• ColdFusion 11+

• Lucee 4.5+

Manual Installation

If you are using LogBox within a ColdBox application context, then LogBox is part of the platform. Just install ColdBox normally. If you are using LogBox standalone, just drop LogBox in your application root or create a mapping called logbox that points to the installation folder. If you can run the following snippet, then LogBox is installed correctly:

logbox = new logbox.system.logging.LogBox();

CommandBox Installation

# Latest CommandBox
box install logbox

# Bleeding Edge
box install logbox@be

Namespaces

Standalone

logbox.system.logging

ColdBox

coldbox.system.logging

Info In this book we will be using the standalone namespace for all examples.

Useful Resources

Luis Fernando Majano Lainez

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, microcontrollers and overall embedded systems.

• He has of late (during old age) become a fan of running and bike riding with his family.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” Proverbs 3:5

Contributors

Jorge Emilio Reyes Bendeck

Jorge started working as project manager and business developer at Ortus Solutions, Corp. in 2013, . At Ortus he fell in love with software development and now enjoys taking part on software development projects and software documentation! He is a fellow Cristian who loves to play the guitar, worship and rejoice in the Lord!

Therefore, if anyone is in Christ, the new creation has come: The old has gone, the new is here! 2 Corinthians 5:17

No matter what configuration you decide to use, you will always have to instantiate LogBox with a LogBoxConfig object: logbox.system.logging.config.LogBoxConfig. However you have the option of either talking directly to this CFC or creating a more portable configuration. This portable configuration we denote as a simple data CFC that contains the LogBox configuration data using what we call our LogBox DSL (Domain Specific Language).

The cool thing about this LogBox DSL is that it is exactly the same whether you are using LogBox in ColdBox applications or in any other framework or non-framework ColdFusion application. So you can configure LogBox by:

1. Creating a portable data CFC using the LogBox DSL or

2. Creating the LogBoxConfig object and interacting with its methods

Our LogBox RefCard will get you up and running in no time

The methods shown below are used to add categories to specific severity levels only. Each method can receive 1 to * category arguments.

• public void debug()

• public void info()

• public void warn()

• public void error()

• public void fatal()

• public void off()

Logbox

You can also add categories with very granular information using the category() method. This method will allow you to add a category definition with a range of severity levels and even a list of which appenders to respond to.

public void category(
    string name,
    [numeric levelMin='0',]
    [numeric levelMax='4',]
    [string appenders='*']
)

Parameters:

Example

//log all email service messages to the MyLogFileAppender and the Console.
config.category( name="org.model.EmailService", appenders="MyLogFileAppender,Console" );

Configuring a root logger is mandatory for LogBox. This is very easy and just a few arguments.

public void root([numeric levelMin="-1",] [numeric levelMax="4",] string appenders)

Parameters

config.root( appenders="*" );
config.root( levelMax="WARN", appenders="console,files" );
config.root( levelMin="INFO", levelMax="DEBUG", appenders="*" );

In order to create a simple data CFC, just create a CFC with one required method on it called configure where you will define the logging configuration data:

**
* A LogBox configuration data object
*/
component{

    function configure(){
        logBox={

        };
    }
}

Base Config

Once you have this shell, you will create a logBox variable in the variables scope that must be a structure with the following keys:

Appenders

To define an appender you must define a struct with a key value which is the internal name of the appender. Each appender name must be unique. You configure each appender with the following keys:

Root Logger

To configure the root logger use the following keys:

Categories

To define categories you must define a struct with a key value which is the internal name of the category. Each category name must be unique. You configure each category with the following keys:

As you might notice the name of the keys on all the structures match 100% to the programmatic methods you can also use to configure logBox. So when in doubt, refer back to the argument names.

Example Configuration

logBox = {
    // Appenders
    appenders = {
        appenderName = {
            class="class.to.appender",
            layout="class.to.layout",
            levelMin=0,
            levelMax=4,
            properties={
                name  = value,
                prop2 = value 2
            }
    },
    // Root Logger
    root = { levelMin="FATAL", levelMax="DEBUG", appenders="*" },
    // Granualr Categories
    categories={
        "coldbox.system" = { levelMin="FATAL", levelMax="INFO", appenders="*" },
        "model.security" = { levelMax="DEBUG", appenders="console" }
    }
    // Implicit categories
    debug = [ "coldbox.system.interceptors"  ],
    info  = [ "model.class", "model2.class2" ],
    warn  = [ "model.class", "model2.class2" ],
    error = [ "model.class", "model2.class2" ],
    fatal = [ "model.class", "model2.class2" ],
    off   = [ "model.class", "model2.class2" ]
};

Instantiation

Once you have defined the configuration data in this object you can now use the same LogBox Config object to either instantiate it for you or you can pass a reference of it by using the init() method of the LogBoxConfig object:

init([CFCConfig,CFCConfigPath])

• CFCConfig : The object instance that has the logbox configuration data

• CFCConfigPath : The instantiation path of the object that has the logbox configuration data

// Using config path
config = createObject( "component", "logbox.system.logging.config.LogBoxConfig" )
    .init( CFCConfigPath="my.path.LogBoxConfig" );
logBox = createObject( "component", "logbox.system.logging.LogBox" ).init( config );

// Using config object
data = createObject( "component", "my.data.CFC" );
config = createObject( "component", "logbox.system.logging.config.LogBoxConfig" ).init( data );
logBox = createObject( "component", "logbox.system.logging.LogBox" ).init( config );

That's it! Using this DSL approach, your configurations are much more portable now and can even be shared in ANY framework, ColdBox or ColdFusion application. So now let's explore how to bypass this data CFC and use the LogBoxConfig object directly. It is important to understand these methods as they are called for you when you define your LogBox DSL data.

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

The first thing you need to do in your config object is add appenders. Each appender is added via the appender() method.

Parameters:

Examples

We recommend using the available can{severity}() methods to determine if we can log at a specific log level before actually writing the logging method line. This is done as best practice in order to avoid processing of messages that will never be logged anyways. So let's look at a very simple example of what NOT to do:

log.debug( "This is my log message, some #dynamic# date is here", dataCFC );

This will call the logger's debug() method, execute the lines of code and then the logger determines if it can be logged or not. This is ok, but we all love performance and best practice, so we encourage you to do the following:

if( log.canDebug() ){
    log.debug( "This is my log message, some #dynamic# date is here", dataCFC );
}

This way, the logger determines if it can send debug log messages, and only IF IT CAN does it. This is faster and cleaner, but you will type more. Sorry!

This appender logs using Java's System.out.println function. Logs will appear in the directory specificied in your CF or Lucee Administrator.

Once you retrieve a logger object from LogBox, you are ready to start sending messages. We already covered how to dynamically add/remove/list/check appenders from a logger, so let's look at the other methods we have available:

Instance Members

Every logger has access to the following public variables:

Utility Methods

Logging Methods

As you can probably tell, all logging methods take in a message string an a second argument called extraInfo. This extraInfo argument can be anything from a string, a structure, a query or whatever. This way you can send in a complex structure that the appenders will serialize into message form or log into the appropriate channel. Thus, extraInfo can be very handy when you are building your own custom appenders.

// setting some messages
myLogger = logBox.getLogger( this ); // "com.model.dao"

myLogger.info( "I just created my first logger" );

try{
    data = dao.getDBData();
}
catch( any e ){
    myLogger.error(
        "Something really died on my dbdata method: #e.message# #e.detail#",
        e.tagContext
    );
}

I hope that by now you understand the basics of loggers and how easy it is to use them.

As we mentioned before, LogBox ships with over 10 different appenders for your logging and tracing needs. Some of them require configuration properties and some don't. We already discovered that when we configure an appender we can pass in a structure of properties much like how we configure ColdBox Interceptors. Each appender can implement as many properties as they see fit. We will digest all the included LogBox appenders and their configuration properties.

Async Property

All appenders have an async boolean property by default inherited from LogBox. This will tell LogBox to log asynchronously in a separate thread. By default all logging is done synchronously

This appender logs directly to the cflog tag by using a custom file or logging to the application logs.

When using any of the logging methods like info(), debug(), warn(), etc, they all take two arguments:

1. The message to log

2. An extraInfoargument which can be anything you like.

This extrainfo argument can be a simple value, a CFC, a complex object and pretty much anything you like. The appenders get this extraInfo argument and process it into their appropriate destinations by serializing its value. This is done by using the following algorithm:

1. If it is a simple value, then just use it.

2. If it is an object then check if the object has a method called $toString(). If the method exists, then call $toString() and use its return value.

3. If it is an object with no $toString() method, then marshall its representation into XML format.

4. If it is a complex variable like a struct, query, array, etc, then marshall it into JSON format.

As you can see from the algorithm above, you can use the extraInfo argument to your benefit to save serialized representations of data to the appenders and then retrieve or re-inflate them later. The $toString() convention is great because you have complete control on how a CFC will serialize to its string representation. Let's see an example on a simple CFC:

// User.cfc
component{

    function $toString(){
        // return my representation as a comma list of values of my properties
        return "#getName()#,#getAge()#,#getEmail()#";
    }
}

So when this object is sent to a logger's method, it will detect it is an object and the $toString() function exists and call it for serialization.

user = userService.getUser( rc.id );

// need to log it.
if( log.canDebug() ){
    log.debug( "User just got logged in right now!", user );
}

This appender directs messages via the cftrace tag. It has no configuration properties.

Just by building a ColdBox application, you get several key benefits when dealing with LogBox.

• First of all, the configuration, creation and instantiation is ALL done for you.

• You can configure LogBox on a per-environment criteria as the ColdBox per-environment routines can use the LogBox configuration elements in its definitions.

• Every handler and interceptor already has a reference to the LogBox instance as a property called: logBox. So you have immediate access to it.

• Every handler and interceptor already has a configured logger instance as a property called: log. So you have immediate access to it.

• You can configure the logging of ColdBox on a per package level.

• You get the power of ColdBox MVC.

The two most important methods are getRootLogger() & getLogger(), which you will use to get the root or named logger objects.

Caution: When you ask for a named category logger and LogBox cannot find its definition, it will create a logger that will inherit its logging levels and appenders from the root logger.

ColdBox allows for a programmatic approach via the ColdBox.cfc configuration object. So let's look at how the ColdBox loader looks at your configuration:

1. Is there a logBox variable defined in the configuration?

   • False:

     • Does a LogBox.cfc exist in the application's config folder?

       • True: Use that CFC by convention to configure LogBox

       • False: Continue to next point

     • Configure LogBox with default framework settings (coldbox.system.web.config.LogBox)

   • True:

     • Have you defined a configFile key?

       • True: Then use that value to pass into the configuration object so it can load LogBox using that configuration file (CFC)

       • False: The configuration data is going to be defined inline here so process it

So the configuration DSL is exactly the same as you have seen in before with the only distinction that you can add a configFile key that can point to an external configuration file (CFC).

Info Please remember to set the autoExpand property to FALSE if you will be using an absolute file path location.

Info Please remember to set the autoExpand property to FALSE if you will be using an absolute file path location.

Every ColdBox application can use LogBox by default since the main engine already uses it. By default ANY ColdBox application will be configured with a LogBox instance with the following appenders:

component{

    function configure(){
        logBox = {};

        // Define Appenders
        logBox.appenders = {
            console = { class="coldbox.system.logging.appenders.DummyAppender" }
        };

        // Root Logger
        logBox.root = {
            levelmax="OFF",
            levelMin="OFF",
            appenders="*"
        };
    }

}

Also, the app will log on ANY severity by default up to INFO for the root logger and the ColdBox package. You can customize this default behavior by creating or modifying the LogBox element in your ColdBox configuration file and follow the same configuration approach as any normal LogBox configuration file.

The ColdBox Proxy (coldbox.system.remote.ColdboxProxy) object also has three utility methods you can use to talk to LogBox from any remote proxy you create:

• getLogBox() : Get a reference to the LogBox instance.

• getRootLogger() : Get a reference to the root logger.

• getLogger(category:any) : Get a named logger instance or reference.

The abstract appender also has various cool methods that you can use when building appenders:

Properties Methods

Utility Methods

Layout Methods

The columns needed or created in the table are

• id : UUID

• severity : string

• category : string

• logdate : timestamp

• appendername : string

• message : string

• extrainfo : string

If you are building a column mapper, the map must have the above keys in it that match to your own table columns.

WireBox DI and Injection can talk to LogBox. This way you can easily use our dependency injection DSL for LogBox related objects:

Below you can see the most common usage of this dependency DSL:

//  LogBox wired in
property name="logBox" inject="logbox";

//  Root Logger
property name="logger" type="logbox:root";

//  Named Category
property name="logger" type="logbox:logger:com.api.model";

//  Category eq to ClassPath
property name="logger" type="logbox:logger:{this}";

The LogBox instance is stored in the ColdBox main controller object (coldbox.system.web.Controller) and you can retrieve it like so from any handler, or interceptor.

logBox = getController().getLogBox();
// or 
logBox

In order to create your own appenders, you will have to create a cfc that extends logbox.system.logging.AbstractAppender and implement the following methods:

init()

The signature of the init method is the following:

<---  Init --->
<cffunction name="init" access="public" returntype="AbstractAppender" hint="Constructor called by a Concrete Appender" output="false" >
    <---  ************************************************************* --->
    <cfargument name="name"         type="string"  required="true" hint="The unique name for this appender."/>
    <cfargument name="properties"     type="struct"  required="false" default="#structnew()#" hint="A map of configuration properties for the appender"/>
    <cfargument name="layout"         type="string"  required="false" default="" hint="The layout class to use in this appender for custom message rendering."/>
    <cfargument name="levelMin"      type="numeric" required="false" default="0" hint="The default log level for this appender, by default it is 0. Optional. ex: LogBox.logLevels.WARN"/>
    <cfargument name="levelMax"      type="numeric" required="false" default="4" hint="The default log level for this appender, by default it is 5. Optional. ex: LogBox.logLevels.WARN"/>
    <---  ************************************************************* --->

</cffunction>

As you can see each appender receives a name, a structure of properties, an optional layout class, and an optional levelMin and levelMax severity levels. The properties and layout are both optional, but you must call the super.init( argumentCollection = arguments ) method in order to have full ok operation on the appender. You can then do your own constructor as you see fit. Here is an example:

<---  Constructor --->
<cffunction name="init" access="public" returntype="FileAppender" hint="Constructor" output="false">
    <---************************************************************** --->
    <cfargument name="name"         type="string"  required="true" hint="The unique name for this appender."/>
    <cfargument name="properties"     type="struct"  required="false" default="#structnew()#" hint="A map of configuration properties for the appender"/>
    <cfargument name="layout"     type="string"  required="true"  default="" hint="The layout class to use in this appender for custom message rendering."/>
    <cfargument name="levelMin"      type="numeric" required="false" default="0" hint="The default log level for this appender, by default it is 0. Optional. ex: LogBox.logLevels.WARN"/>
    <cfargument name="levelMax"      type="numeric" required="false" default="4" hint="The default log level for this appender, by default it is 5. Optional. ex: LogBox.logLevels.WARN"/>
        <---************************************************************** --->
    <cfscript>
        super.init(argumentCollection=arguments);

        // Setup Properties
        if( NOT propertyExists("filepath") ){
            $throw(message="Filepath property not defined",type="FileAppender.PropertyNotFound");
        }
        if( NOT propertyExists("autoExpand") ){
            setProperty("autoExpand",true);
        }
        if( NOT propertyExists("filename") ){
            setProperty("filename",getName());
        }
        if( NOT propertyExists("fileEncoding") ){
            setProperty("fileEncoding","UTF-8");
        }

        // Setup the log file full path
        instance.logFullpath = getProperty("filePath");
        // Clean ending slash
        if( right(instance.logFullpath,1) eq "/" OR right(instance.logFullPath,1) eq "\"){
            instance.logFullPath = left(instance.logFullpath, len(instance.logFullPath)-1);
        }
        instance.logFullPath = instance.logFullpath & "/" & getProperty("filename") & ".log";

        // Do we expand the path?
        if( getProperty("autoExpand") ){
            instance.logFullPath = expandPath(instance.logFullpath);
        }

        //lock information
        instance.lockName = getname() & "logOperation";
        instance.lockTimeout = 25;

        return this;
    </cfscript>
</cffunction>

logMessage()

The signature of the logMessage method is the following:

<---  logMessage --->
<cffunction name="logMessage" access="public" output="false" returntype="void">
    <cfargument name="logEvent" type="logbox.system.logging.LogEvent" required="true" hint="The logging event to log.">
</cffunction>

As you can see it is a very simple method that receives a LogBox logging event object. This object keeps track of the following properties with its appropriate getters and setters:

• timestamp

• category

• message

• severity

• extraInfo

You can then use this logging event object to log to whatever destination you want. Here is a snippet from our scope appender:

<---  Log Message --->
<cffunction name="logMessage" access="public" output="true" returntype="void" hint="Write an entry into the appender.">
    <---************************************************************** --->
    <cfargument name="logEvent" type="logbox.system.logging.LogEvent" required="true" hint="The logging event"/>
    <---************************************************************** --->
    <cfscript>
        var logStack = "";
        var entry = structnew();
        var limit = getProperty('limit');
        var loge = arguments.logEvent;

        // Verify storage
        ensureStorage();

        // Check Limits
        logStack = getStorage();

        if( limit GT 0 and arrayLen(logStack) GTE limit ){
            // pop one out, the oldest
            arrayDeleteAt(logStack,1);
        }

        // Log Away
        entry.id = createUUID();
        entry.logDate = loge.getTimeStamp();
        entry.appenderName = getName();
        entry.severity = severityToString(loge.getseverity());
        entry.message = loge.getMessage();
        entry.extraInfo = loge.getextraInfo();
        entry.category = loge.getCategory();

        // Save Storage
        arrayAppend(logStack, entry);
        saveStorage(logStack);
    </cfscript>
</cffunction>

onRegistration() & onUnregistration()

Finally, both the onRegistration and onUnregistration methods have to be void methods with no arguments.

<cffunction name="onRegistration" access="public" hint="Runs after the appender has been created and registered. Implemented by Concrete appender" output="false" returntype="void">
</cffunction>

<cffunction name="onUnRegistration" access="public" hint="Runs before the appender is unregistered from LogBox. Implemented by Concrete appender" output="false" returntype="void">
</cffunction>

These are great for starting or stopping your appenders if they so need to. Here is a sample from our socket appender:

<---  onRegistration --->
<cffunction name="onRegistration" output="false" access="public" returntype="void" hint="When registration occurs">
    <cfif getProperty("persistConnection")>
        <cfset openConnection()>
    </cfif>
</cffunction>

<---  onRegistration --->
<cffunction name="onUnRegistration" output="false" access="public" returntype="void" hint="When Unregistration occurs">
    <cfif getProperty("persistConnection")>
        <cfset closeConnection()>
    </cfif>
</cffunction>

You can programmatically register appenders at runtime by using the registerAppender() function exposed in the LogBox object. Here is the function API:

registerAppender(name, class, [properties={},] [layout="",] [levelMin=0,] [levelMax=4]);

Info Please note that registering dynamic appenders at runtime is tricky as some objecs might already have references to some appenders. We recommend registering appenders at configuration load or when the application starts up.

In order for an appender to deal with custom layouts, you must use the layout methods when preparing to log your messages. Below is a simple example from the console appender of how to do this:

if( hasCustomLayout() ){
  entry = getCustomLayout().format(loge);
}
else{
  entry = "#severityToString(loge.getseverity())# #loge.getCategory()# #loge.getmessage()# ExtraInfo: #loge.getextraInfoAsString()#";
}

// Log message to system.out
instance.out.println(entry);

As you can see, all you need to do is have an if statement that checks whether the appender has a custom layout or not and then assign the return of the layout as your message to log.

Every layout has access to the following public variables:

You can easily create a custom layout object by creating a cfc that extends our abstract layout object: logbox.system.logging.Layout and implementing a format() method. Below you can see the method signature:

<---  format --->
<cffunction name="format" output="false" access="public" returntype="string" hint="Format a logging event message into your own format">
    <cfargument name="logEvent" type="logbox.system.logging.LogEvent"   required="true"   hint="The logging event to use to create a message.">
</cffunction>

All you need to do is inspect the logging event and create your very own message and then return it back. That's it! You thought there was more?

Every Appender has access to the following public variables: