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

ColdBox 7.2.0 Released

ColdBox 7.2.0 Released

ColdBox, a widely used development platform for ColdFusion (CFML), has unveiled version 7.2. Packed with compelling new features, bug fixes, and enhancements, this release is designed to empower developers by boosting productivity, refining scheduled task capabilities, and enhancing the overall reliability and efficiency of application development. This article will delve into the key highlights of ColdBox 7.2 and elucidate how these advancements can positively impact developers in their daily coding endeavors.

Luis Majano
Luis Majano
November 20, 2023
Into the Box 2023 Series on CFCast

Into the Box 2023 Series on CFCast

Excitement is in the air as we unleash the highly anticipated ITB 2023 series exclusively for our valued CFCast subscribers – and the best part? It's FREE for CFCast members! Now is the perfect time if you haven't joined the CFCast community yet. Plus, we've got an incredible End-of-Year deal that's too good to miss

Maria Jose Herrera
Maria Jose Herrera
November 20, 2023
Ortus Deals are Finally Here!

Ortus Deals are Finally Here!

The much-anticipated Ortus End-of-the-Year Sale has arrived, and it's time to elevate your development experience! Whether you're a seasoned developer, a tech enthusiast, or someone on the lookout for top-notch projects, Ortus has something special in store for you. Brace yourself for incredible discounts across a wide array of products and services, including Ortus annual events, books, cutting-edge services, and more.

Maria Jose Herrera
Maria Jose Herrera
November 15, 2023