Daniel Garcia

June 21, 2022

Spread the word

Share your thoughts

The ColdBox Debugger (cbDebugger) module is “a light-weight performance monitor and profiling tool for ColdBox applications” that can be used to see what is going on with your site. It can monitor any ColdBox site, from frontend sites with views to REST API sites. It can also track many things and give insights into requests, CacheBox caches, database activity (including cborm, quick, qb, and Adobe CF 2018+). It has also been recently updated to use Alpine JS as well as other enhancements. If you have not used ColdBox Debugger in a while, it is time to take another look.

Getting Started

First, go to ForgeBox and see all the awesome features of ColdBox Debugger, including information on the various settings.

Adding this module to your site is as easy as

  1. Installing the module (via CommandBox is simplest)
    1. From CommandBox, go to your site and Run box install cbdebugger
  2. Adding the cbDebugger module settings to your config/ColdBox.cfc
    1. See sample config below (same as on ForgeBox)
  3. Reinitializing the site
  4. Viewing the debugger panel (either at the bottom of the site or via the /cbDebugger)

Although the ColdBox debugger has many features that you can utilize (seriously, please view the ForgeBox link), we are going to get started with a basic configuration of:

moduleSettings = {
	// Debugger Settings
	cbDebugger = {
		// Master switch to enable/disable request tracking into storage facilities.
		enabled : true,
		// Turn the debugger UI on/off by default. You can always enable it via the URL using your debug password
		// Please note that this is not the same as the master switch above
		// The debug mode can be false and the debugger will still collect request tracking
		debugMode : true,
		// The URL password to use to activate it on demand
		debugPassword  : "cb:null",
		// This flag enables/disables the end of request debugger panel docked to the bottom of the page.
		// If you disable it, then the only way to visualize the debugger is via the `/cbdebugger` endpoint
		requestPanelDock : true,
		// Request Tracker Options
		requestTracker : {
			// Track all cbdebugger events, by default this is off, turn on, when actually profiling yourself :) How Meta!
			trackDebuggerEvents          : false,
			// Store the request profilers in heap memory or in cachebox, default is cachebox. Options are: local, cachebox
			storage                      : "cachebox",
			// Which cache region to store the profilers in if storage == cachebox
			cacheName                    : "template",
			// Expand by default the tracker panel or not
			expanded                     : true,
			// Slow request threshold in milliseconds, if execution time is above it, we mark those transactions as red
			slowExecutionThreshold       : 1000,
			// How many tracking profilers to keep in stack: Default is to monitor the last 20 requests
			maxProfilers                 : 50,
			// If enabled, the debugger will monitor the creation time of CFC objects via WireBox
			profileWireBoxObjectCreation : false,
			// Profile model objects annotated with the `profile` annotation
			profileObjects               : false,
			// If enabled, will trace the results of any methods that are being profiled
			traceObjectResults           : false,
			// Profile Custom or Core interception points
			profileInterceptions         : false,
			// By default all interception events are excluded, you must include what you want to profile
			includedInterceptions        : [],
			// Control the execution timers
			executionTimers              : {
				expanded           : true,
				// Slow transaction timers in milliseconds, if execution time of the timer is above it, we mark it
				slowTimerThreshold : 250
			// Control the coldbox info reporting
			coldboxInfo : { expanded : false },
			// Control the http request reporting
			httpRequest : {
				expanded        : false,
				// If enabled, we will profile HTTP Body content, disabled by default as it contains lots of data
				profileHTTPBody : false
		// ColdBox Tracer Appender Messages
		tracers     : { enabled : true, expanded : false },
		// Request Collections Reporting
		collections : {
			// Enable tracking
			enabled      : false,
			// Expanded panel or not
			expanded     : false,
			// How many rows to dump for object collections
			maxQueryRows : 50,
			// Max number to use when dumping objects via the top argument
			maxDumpTop: 5
		// CacheBox Reporting
		cachebox : { enabled : false, expanded : false },
		// Modules Reporting
		modules  : { enabled : false, expanded : false },
		// Quick and QB Reporting
		qb       : {
			enabled   : true,
			expanded  : false,
			// Log the binding parameters
			logParams : true
		// cborm Reporting
		cborm : {
			enabled   : false,
			expanded  : false,
			// Log the binding parameters (requires CBORM 3.2.0+)
			logParams : true
  		// Adobe ColdFusion SQL Collector
 		acfSql : {
			enabled   : false,
			expanded  : false,
			// Log the binding parameters
			logParams : true
		// Async Manager Reporting
		async : {
			enabled : true,
			expanded : false

In this setup, we are:

  • Enabling the debugger
  • Enabling the docking panel
  • Enabling qb database activity

If you do not like having the request panel at the bottom, set requestPanelDock requestPanelDock to false. You can still view the debugger at /cbDebugger

You can play around with the various settings to track what you need but be aware that the more you enable, the slower things will be. These defaults are fine, but if you were to enable something like collections you could see some issues.

Note for API usage: You absolutely can use this for your API site, you will just need to access the debugger panel at /cbDebugger.

You can also consider adding environment variables to control whether specific settings are enabled or not. As you switch sites, updating those values can make it easier to manage without having to change any config code.

Example: enabled : getSystemSetting( "CBDEBUGGER_ENABLED", false )

That is all it takes to set up and use ColdBox Debugger!

Add Your Comment

Recent Entries

Ortus Black Friday Deals are here!

Ortus Black Friday Deals are here!

Make 2023, the year you finally start modernizing your CFML projects with our Black Friday deals!

Don't waste any more time trying to find solutions, we got everything you need to rock your projects and learn new skills that will save you time and money while delivering a quality service. 

From Nov 25th to Dec 1st

Maria Jose Herrera
Maria Jose Herrera
November 25, 2022
Call For Speakers Open for Into The Box 2023

Call For Speakers Open for Into The Box 2023

We are very excited that the Into The Box conference is coming back to the Houston area and FINALLY on our normal schedule of May of 2023. Registration is now officially open and call for papers is now open as well. We are also extremely excited that this will be our 10 year anniversary for the Into The Box Conference. So we will defintely go all out!

  • Full 2-day conference with over 30 different technology topics
  • An additional full day of hands-on training available for a veritable 3 days of awesomeness
  • A warm and sunny city of The Woodlands, Texas
  • When: May 17-19 of 2023
  • Modernize Your Skillz
  • Party with our live Mariachi Band!

Luis Majano
Luis Majano
November 11, 2022
New Patreon Perk: Ortus Software Craftsmanship Book Club

New Patreon Perk: Ortus Software Craftsmanship Book Club

What is the Software Craftsmanship Book Club?

Its a place for CFML Community members can get together, discuss and debate the thoughts, ideas, best practices outlined by a series of books focusing on increasing Software Developers efficiency, productivity and pride. It will be relaxed but educational environment, where we can learn from each other, and grow as a community.


Ortus Software Craftsmanship Book Club

Maria Jose Herrera
Maria Jose Herrera
November 09, 2022