Blog

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.

https://www.forgebox.io/view/cbdebugger

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

Live Stream Series - Koding with the Kiwi + Friends - July 1st 2022 Recap

Live Stream Series - Koding with the Kiwi + Friends - July 1st 2022 Recap

In our last session, Daniel and Gavin worked through a lot of content, what is the OpenAPI and Swagger Doc, some tools like editor.swagger.io and Daniel's CBSwaggerUI module. They looked at how to add tags, security, parameters, requestbody, responses and got side tracked down a really interesting rabbit hole after a question from one of the Patreons. Find out more and how to watch last weeks stream.

Gavin Pickin
Gavin Pickin
July 05, 2022
Ortus Content Digest for week of July 1st

Ortus Content Digest for week of July 1st

What has Ortus been publishing this week? We have the CFML News Podcast, more ITB Workshop Podcasts, some CFCasts and YouTube Videos, lots of Ortus and ITB Blog Posts. We have a lot more planned for next week as well

Gavin Pickin
Gavin Pickin
July 01, 2022