Added

• ColdBox 7 support

• New TimerDelegate that can be used to add timer functions to any model

• Timer service rewritten to support nesting and included metadata

• Ability to open views and layouts from the execution timers in any Code Editor

• New WireBoxCollector which is only used if enabled. This greatly accelerates the performance of the request collector since before they where in the same collector.

• Ability to open CFCs that are profiled by the WireBox Collector in any Code Editor.

• Ability to open the Handler events that are profiled by the Request Collector in any Code Editor.

• New life-cycle events: onDebuggerUnload, onDebuggerLoad

• Ability for the custom timeIt() functions to accept metdata to store in the execution timer

• New Slowest Queries panel for cborm, acf, and qb/quick

• New visualizer total db time as well as request time including percentage of the request time

• Ability to export a profiler in json

• Ability to sort the visualizer's profilers

Fixed

• Timer service reconstructing the timer hashes and profilers twice.

• timeIt() helper was not passing the closure correctly

• If doing a fwreinit on the visualizer, the current profiler was still being show even thought it was empty. Add an empty check to avoid the big bang!

Changed

• Tracers are now streamlined and stored alongside the request profilers

• Small UI fixes on request profiler HTTP methods

• WireBox collecting is now done by the WireBox collector not the Request Collector.

• Adobe 2016 Dropped

In this section, you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 4.0

We continue to set the foundations of an HQ service with the addition of ColdBox 7 support, new collectors, performance optimizations, slowest transactions, and much more.

Version 3.0

This was a complete rewrite of the module to support standalone capabilities and the foundation of the upcoming CBDebugger HQ.

We migrated the entire UI to leverage AlpineJS and ColdBox Elixir and set the foundation of the new upcoming UI rewrite.

Added SQL support for ORM and Adobe queries with IDE integrations.

Version 2.0

A movement to modern engines and a streamlined UI for inclusion in all applications. REST Application support was added alongside ColdBox 6 support.

Version 1.0

The initial release.

Added

• New github actions

• Donot enable debugger in testing mode

Welcome To The ColdBox Debugger Module

The ColdBox Debugger module is a lightweight performance monitor and profiling tool for ColdBox applications. It can generate a nice debugging panel on every rendered page or a dedicated visualizer to make your ColdBox application development nicer, more funner and greater! Yes, funner is a word!

Capabilities

The ColdBox Debugger tracks your requests, whether Ajax, traditional, or REST, its environment, execution, etc. Here is a listing of some of the capabilities you get with the ColdBox Debugger:

• Track all incoming requests to your applications

• Track exceptions and execution environment

• Track incoming HTTP requests, parameters, body, and much more

• Track final request collections

System Requirements

• Lucee 5+

• ColdFusion 2018+

• ColdBox 6+

Versioning

ColdBox Debugger is maintained under the guidelines as much as possible. Releases will be numbered in the following format:

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bump the patch

License

Apache 2 License: ​

Important Links

• Source:

• ForgeBox:

• Community:

• Issues:

Professional Open Source

This module is professional open-source software backed by offering services like:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

​

The async collector can be activated so you can visualize the applications executors and tasks.

// Async Manager Reporting
async    : { enabled : true, expanded : false }

Configuration

The source code for this book is hosted on GitHub: . You can freely contribute to it and submit pull requests. Ortus Solutions, Corp copyrights the contents of this book and cannot be altered or reproduced without the author's consent. All content is provided "As-Is" and can be freely distributed.

• The majority of code examples in this book are done in cfscript.

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL -

The CBDebugger ships with a LogBox appender called the TracerAppender that if enabled it will intercept all log calls into the ColdBox Debugger tracers panel. It will show the log with it's log level and even the complex extra information. The default log levels for the appender are:

• min : fatal

• max : debug

The modules collector can be activated and it will profile and track all of your application's ColdBox modules. Specifically the registration and activation execution times. You can also reload and unload the modules if needed.

Configuration

In an event-driven framework like ColdBox, there are tons of events that fire within traditional request/response transactions. You can activate our tracker and we will trace and profile interception calls. Activate it via the settings first:

Once activated, you can add a collection of interception points to profile in your application. We will track them for you and even if they are ORM calls we will tell you which entity initiated the call.

There will be cases where you need to test the performance of the creation of certain objects in WireBox. You can do so by activating the profileWireBoxObjectCreation setting in the requestTracker. Once enabled, you will see the profiling of all objects created by WireBox in the debug timers.

The debugger can be enabled via URL commands if needed in public facing applications with a combination of two url keys:

• debugMode:boolean - Control to turn the debugger on/off

• debugPassword:string - The secure password to use to enable the debugger

Please see the on how to add the default debug mode and debug password. If your debug password is validated and you turn on debug mode a secured cookie will be stored for you and you will be able to visualize the debugger. Once you turn it off, then it will remove this cookie for you.

You can use the hyper configuration structure to configure the hyper panel in the debugger. This will track all outgoing http/s calls made by the Hyper module in your debugger.

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer that has been developing and designing software systems since the year 2000. He was born in San Salvador, El Salvador in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University. Luis resides in Houston, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion/Java projects. You can read his blog at

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” Proverbs 3:5

The ColdBox debugger allows you to profile the execution of ANY method in ANY CFC via our AOP pointcuts. All you need to do is add the profile annotation to a method or component declaration in your model/ORM objects. Once you do, the debugger will track the execution of those methods in the debug timers panel for you. First thing to do is make sure the setting is turned on:

requestTracker : {
	// Profile model objects annotated with the `profile` annotation
	profileObjects               : true,
	// If enabled, will trace the results of any methods that are being profiled
	traceObjectResults           : false,
}

The traceObjectResults if true will track the actual results of the method calls into your debugger timer panel. Careful, as we will serialize anything you send to us. Then add the profile annotation to any method or CFC.

/**
 * Profile all methods in this component
 */
component profile{

}

// Add the profile to this method to track it
function saveAllObjects() profile{

}

Profiling objects is great because you can just annotate and forget. Nothing to turn off in production. However, just note that doing AOP abstractions on more methods, the more slow downs you will experience, especially on transient objects. We would recommend that you use it on specific methods only and be very wearisome of using the tracing of object results.

The qb collector can be activated if you are using the our qb module and/or quick ORM. It will then track all calls made with raw qb sql and quick entities.

qb   : { enabled : false, expanded : false, logParams : true }

Configuration

The luceeSql collector can be activated if you are in a Lucee engine and it will track all SQL calls made by your application. You can event choose to show the biding parameters or not.

// Lucee SQL Collector
luceeSql   : { enabled : false, expanded : false, logParams : true }

Configuration

The cborm collector can be activated if you are using the ColdFusion ORM and our cborm module. It will then track all calls made with criteria queries, query executions and much more.

cborm   : { enabled : false, expanded : false, logParams : true }

Configuration

The acfSql collector can be activated if you are in an Adobe engine and it will track all SQL calls made by your application. You can event choose to show the biding parameters or not.

Configuration

CBDebugger 4.2 comes action-packed with tons of new features, improvements and bug fixes. Let's check out the major areas of improvement.

Hyper Collector

You can now track Hyper http/s requests right in a new panel. It will also aggregate the request's total time, slowest, grouped, and timeline. It also comes with some great options for configuration:

You can use the collections configuration structure to configure the collections panel in the debugger. This will dump out the rc and the prc collections with the final snapshot of their data. We recommend that you only enable this collector with the appropriate dump top levels as it can completely crash your server trying to dump out all the variables in the collections.

// Request Collections Reporting
collections : {
	// Enable tracking
	enabled      : false,
	// Expanded panel or not
	expanded     : false,
	// How many rows to dump for object collections
	maxQueryRows : 50,
	// How many levels to output on dumps for objects
	maxDumpTop   : 5
}

Apart from debugging the incoming request and presenting the debugger at the end of the request (Request Dock Panel), you can also navigate to /cbdebugger and visualize the Debugger request tracker. This panel will monitor ALL incoming requests to your application: REST, SOAP, Ajax, etc.

You can execute several commands from this visualizer:

• Clear all request history

• Reinit ColdBox

• Shutdown the debugger visualizer

• Refresh the requests

• Auto-refresh the requests

• Produce a Java Heap Dump

Each request is also tracked and visualized according to its activated collectors.

Storage

You can use the requestTracker.storage setting to configure where the request trackers are stored. The default values are:

• memory : The default, which stores the trackers in memory

• cachebox : Store the request trackers in a CacheBox provider via the cacheName

  • cacheName

Max Profilers

The debugger comes pre-configured to store a stack of 50 requests in memory. You can change this via the following setting:

Track Debugger Events

If you wanted to profile even the debugger itself you can use the trackDebuggerEvents flag if needed.

Slow Execution Painting

The debugger can paint requests in a different color if they are executing slower than the threshold setting shown below. Please note that the threshold is in milliseconds.

Execution Timers

Each request tracker has a panel called ExecutionTimers which shows all the timers the debugger was able to track during that request. You can configure it via the following settings:

The expanded is just a simple boolen to control if the panel is open by default, which it is. The slowTimerThreshold is in milliseconds and when a timer passes that threshold it will be painted red; like the screenshot above.

ColdBox Info Panel

You can control if the ColdBox information panel is open or closed by default via the coldboxInfo setting:

HTTP Request Panel

You can also configure the HTTP Request panel to do your bidding:

You can have the panel open or closed and even chose if the HTTP Body request will be stored or not.

Exception Tracking

All requests that produce exceptions are also tracked and special exception collectors are activated automatically to store the produced exception:

It will store the stack trace and the tag context of the exception so you can visualize it and fix your bug. It will also have links to open the offending code in VSCode or your favorite editor right from the debugger. You can even open and navigate the tag context in your IDE from the debugger.

You can also see all the collectors and their information to the point of the exception:

The debugger can be extended by listening to several events it fires. Here is a collection of such events and the data they emit.

beforeDebuggerPanel / afterDebuggerPanel

beforeProfilerReportPanels / afterProfilerReportPanels

onDebuggerLoad / onDebuggerUnload

No event data emitted

onDebuggerRequestTrackerCreation

This event is fired once the debugger is ready to start tracking the request. You can use the structure to incorporate anything into it.

onDebuggerProfilerRecording

This event is fired right before the request tracker struct is stored in permanent storage. Your last chance to add data into the tracker structure.

Leverage CommandBox to install into your ColdBox app:

You will now have to configure the debugger for it to start tracking your application. This will activate the debugger in your application and render out at the end of a request as a dock or by visiting the debugger request tracker visualizer at /cbdebugger.

WireBox Mappings

Once the module is activated, the following model objects will be available for you:

• debuggerService@cbdebugger - The main debugger service

• JVMUtil@cbdebugger - Useful for creating thread dumps and heap dumps

• timer@cbdebugger - Useful to time operations

WireBox Delegates

We ship the following delegates:

• TimerDelegate@cbdebugger

You can use it to add timing capabilities to any CFC:

The available methods for delegation are:

Mixin Helpers

We also add several helpers to all interceptors, layouts, views, and handlers:

Optional Requirements

cborm Collector

• Hibernate extension (on Lucee)

• orm package on ACF 2021+

Adobe SQL Collector

• cbdebugger package on ACF 2021+

• Check Database Activity on the debugger page or cfconfig setting

Lucee SQL Collector

Enable debug logging and database activity in the Lucee Debugging screens or via cfconfig:

The cacheBox collector can be used to visualize the cache configurations, provider zones and a cache content report.

Configuration

The debugger is highly configurable, and we have many settings to assist you in your development adventures and performance tuning. The debugger works by activating data collectors and configuring them. Please note that the more collectors you activate, the slower your application can become. By default, we have pre-selected defaults, which add negligible performance to your applications.

Collectors

The ColdBox Debugger collectors are powerful listeners used for debugging and analyzing applications built on ColdBox. These collectors gather various types of information and statistics during the execution of an application, allowing developers to gain insights into the application's behavior and performance.

The collectors are designed to capture data related to different aspects of an application, such as request information, execution times, database queries, cache usage, and log messages. Please note that each collector can have its own configuration options.

Config

If you are in ColdBox 6, add the following configuration settings to the moduleSettings structure in your config/Coldbox.cfc or if you are in ColdBox 7+ you can create a config/modules/cbdebugger.cfc and add your configuration. Here is the default configuration CBDebugger ships with:

Master Switch

You can enable or disable the request tracking globally via the enabled master switch, make sure to set debugPassword

Debug Mode

The in production environments and enabled via our URL password actions. This allows you to profile your application and then turn on the debugger just for YOU via our debugging cookies.

In development environments where no password is needed use the follwing setting debugPassword : "", cb:null will generate a random password.

If you can't access the debugger pannel, you might need to add debugmode=1 to your request

Request Panel Dock

You can enable/disable the rendering of our request panel dock which shows the profiling of the request.