Blog

Debugging & Logging with ColdBox

Abilio Posada June 30, 2023

Spread the word

Abilio Posada

June 30, 2023

Spread the word


Share your thoughts

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

cbDebugger logo

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.

01.jpg

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.

Cache

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.

LogBox logo

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.

MethodDescription
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.:

Add Your Comment

Recent Entries

Must-See ITB 2025 Sessions for TestBox Users!

Must-See ITB 2025 Sessions for TestBox Users!

Are you a fan of TestBox or looking to level up your testing game in 2025? Whether you're just getting started with unit testing or you're already building advanced specs for ColdBox and BoxLang apps, Into the Box 2025 has an exciting lineup tailored just for you. Into the Box 2025 has an exciting lineup tailored just for you. With the recent launch of TestBox 6.3.0 we have amazing new tools, features and tips and tricks to get your testing experience to the next level, review our sessions and test like a pro efficiently and easy!

From hands-on testing strategies to BoxLang innovations, here are the sessions you won’t want to miss this May — and why they matter to you as a TestBox user.

Maria Jose Herrera
Maria Jose Herrera
April 17, 2025
The Into the Box 2025 Agenda is LIVE and Done!

The Into the Box 2025 Agenda is LIVE and Done!

The wait is over! The official Into the Box 2025 agenda is now live — and it's packed with high-impact sessions designed for modern CFML and BoxLang developers. Whether you’re building APIs, modernizing legacy apps, diving into serverless, or exploring AI integrations, this is the conference you’ve been waiting for.

Here’s a look at what you can expect — categorized by key topics to help you plan your learning journey, there’s something for everyone covering modern CFML tools and BoxLang:

Maria Jose Herrera
Maria Jose Herrera
April 15, 2025
Only 2 Days Left to Lock In Early Bird Pricing for Into the Box 2025!

Only 2 Days Left to Lock In Early Bird Pricing for Into the Box 2025!

The countdown is on. You have just two days left to secure your Early Bird ticket  for just $199 to Into the Box 2025 before prices increase on April 16.

We are proud to offer an engaging and high-value online experience for developers around the world. With a virtual ticket, you get more than just access — you get ongoing value that supports your growth long after the conference ends.

Maria Jose Herrera
Maria Jose Herrera
April 14, 2025