Logging and Debugging with ColdBox

Brief intro

Every developer has ever felt or asked themselves one of the following questions more than once in their life:

• Are you exhausted from using writeDump() each time you have problems?
• Do you spend more time-solving issues than creating new features?
• Is a legacy block code giving you a headache?
• Have you ever had nightmares and dreams in which you fix everything but forget it once you wake up?
• Still, troubleshooting your ColdBox apps the old-fashion way?
• Are you reading this like a television advertisement?

If your answers were yes to almost all of those questions, let me tell you about our powerful tools called cbDebugger & LogBox (To be sold separately, just kidding, they are open-source and free), which are going to help us with tons of features:

• Track all incoming HTTP requests, final request collections, parameters, body in your applications by doing it in memory or offloaded cache.
• Track exceptions and execution environment
• Track Hibernate and CBORM queries, criteria queries, and session stats.
• Track QB and Quick queries, entities, and stats.
• Tap into LogBox via our Tracer messages and discover logging on a per-request basis.
• Profile execution and results of ANY model object and ANY ColdBox interception point
• Custom Timer helpers for adding timing methods and annotations anywhere in your code
• Profile your production or development apps with ease.
• Track ColdBox modules and lifecycles.
• Highly configurable and extensible
• Track Adobe ColdFusion Queries (ColdFusion 2018+)
• Allows you to quickly build upon its logging framework to meet any logging or reporting needs your application has
• Categorizes your logging and/or tracing statements according to user-defined categories that can be configured at runtime or pre-runtime
• Categorizations can have their own logging level ranges (such as debug or info)
• Allows you to create multiple destinations for your loggings or change them at runtime
• Offers you the capabilities to filter out or cancel logging noise a-la-carte

Debugging

NOT a boring practice with ColdBox

Installation

Super easy to install and start using with our terminal powered by CommandBox.

box install cbdebugger --saveDev

Note: --saveDev flag is important since we want to debug in development environment only.

Once the module is installed will be automatically activated to be used with the default settings. You will notice in your footer section a new collapsable panel when running in development mode.

There is a useful visualizer that will help us with you history just by adding /cbDebugger to the root of our hostname in the URL

Settings

Inside of your project with cbDebugger installed, locate config/Coldbox.cfc and search for the moduleSettings struct, add the key cbDebugger with the options you require:

moduleSettings = {

	// Debugger Settings
	cbDebugger = {

		// Master switch to enable/disable request tracking into storage facilities.
		enabled : true,

		// Turn UI on/off. You can enable it via URL with debug password. Debugger will still collect request tracking
		debugMode : true,

		// The URL password to use to activate it on demand
		debugPassword : "cb:null",

		// Shows or not the debugger panel docked at the bottom of the page. If disabled the only way to visualize the debugger is via the `/cbdebugger` endpoint
		requestPanelDock : true,

		// Request Tracker Options
		requestTracker : {
			...
		},

		// ColdBox Tracer Appender Messages
		tracers     : { enabled : true, expanded : false },

		// Request Collections Reporting
		collections : { enabled : false, expanded : false },

		// CacheBox Reporting
		cachebox    : { enabled : false, expanded : false },

		// Modules Reporting
		modules     : { enabled : false, expanded : false },

		// Quick and QB Reporting
		qb          : { enabled : true, expanded : false },

		// CBORM Reporting
		cborm       : { enabled : false, expanded : false },

  		// Adobe ColdFusion SQL Collector
 		acfSql      : { enabled : true, expanded : false }
	}
}

There are much more options you can setup. Please feel free to visit this module in our package manager ForgeBox to learn more.

Databases

One of the most powerful thing is the ability of get a tracker of your database queries even with a traditional queryExecute() or ORMExecuteQuery() for Hibernate including objects more complex as CBORM or Quick/QB entities (Must be previously configured)

Cache

You can also enable the CacheBox monitor and get complete insight into all your registered application caches.

Logging

Logging is essential when you are trying to replicate an error, need to know what happened to a server which is remote or with limit access. It gives you a history list of messages with dates and times those messages could be informative, warnings, errors or simple default “logs”. For more information go to our GitHub repository and start contributing in our projects.

A !Boring Practice

Installation

Just copy and paste the following block of code in your terminal placed on your project root folder. This will be possible thanks to CommandBox:

box install logbox

Or you can download an standalone version if you are using CFML without any framework (Please consider to change to our Incredibly Awesome ColdBox Platform Framework)

Configuration

As most of the modules you can setup everything via config/Coldbox.cfc and search for the moduleSettings struct, add the key logBox with the options you require:

//LogBox DSL
logBox = {

	// Configuration file without file extension to use for operation, instead of using this structure
	configFile = "config/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" ]
};

Using it

The following is a list of methods that you could use, the two most important are getRootLogger() & getLogger(), which you will use to get the root or named logger objects.

Method	Description
LogBoxConfig getConfig()	Get the config object registered
Logger getLogger( any category )	Get a named logger object using a category string or the object you will log from
Logger getRootLogger()	Get a reference to the root logger
string getVersion()	Get the current version of LogBox
string getCurrentAppenders()	Get a list of currently registered appenders
string getCurrentLoggers()	Get a list of currently instantiated loggers
void configure( LogBoxConfig config )	Dynamically re-configure the LogBox library

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

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

Summary

Remember:

Time is what we want most, but what we use worst.

— William Penn

We would like to suggest that you prioritize making your life easier by spending less time fixing bugs and more time creating beautiful code. Take the time to debug and improve what you can, while keeping track of your progress. To truly be a professional, make use of our tools and feel free to discuss them with others. We invite you to check out our previous ColdBox 7 roadshow blog posts for even more amazing features and to leave your comments and feedback.:

• Jon Clausen: Delegates - The Lightning of (Coldbox 7) Empowerment
• Alan Quinlan: Async Your Future with ColdBox 7
• Daniel Garcia: 5 Benefits of Using ColdBox to Build Your REST API
• Esmeralda Acevedo: Configurations Outside the Coldbox CFC with ColdBox 7
• Grant Copley: ColdBox Application Templates