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

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.

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:

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:

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!