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

Secure your Agency Against Cyberattacks

Secure your Agency Against Cyberattacks

Recent incidents, such as the compromise of federal agencies through Adobe ColdFusion vulnerabilities, underscore the pressing need for comprehensive cybersecurity measures. In this blog post, we delve into the urgency of fortifying your agency's defenses and present "10 Reasons Why It's Time to Secure Your Agency Against Cyberattacks.”

Maria Jose Herrera
Maria Jose Herrera
December 07, 2023
Into the Box Latam 2023 | Rueda de Prensa

Into the Box Latam 2023 | Rueda de Prensa

En este artículo, exploraremos las reseñas, notas y publicaciones en redes sociales, revistas digitales y blogs de noticias que han surgido a raíz de este emocionante evento que tuvo lugar el jueves 30 de noviembre.

Maria Jose Herrera
Maria Jose Herrera
December 07, 2023
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