ColdFusion Debugging
ColdFusion provides a number of debugging tools to assist us in troubleshooting problem areas. Problem areas could be anything from strange results being output from a query, to a slow running template.
ColdFusion's debugging tools, provides us with extra information that we (and our users) don't normally see when visiting the website.
When running a debugger, you should attempt to do so in a development environment. Obviously, this makes sense if you're only in development mode anyway, but, if you're debugging an issue that's occuring in a production environment (where real users are impacted), you should really try recreating the issue on your development environment. Having said that, there are ways of restricting debug output so that your users aren't affected.
The following ColdFusion tools/tags can be useful for debugging your applications:
- The
<cfdump>tag - The
<cfabort>tag - Debugging Settings (via ColdFusion Administrator)
Below is an overview of each.
The <cfdump> Tag
The <cfdump> tag is a very handy debugging tool for ColdFusion developers. It allows you to output (or "dump") the contents of your variables on the screen. You can use this on any variable, regardless of it's type — arrays, structures, query objects etc
The great thing about <cfdump> is it's ease of use. The syntax is as follows:
Example of Usage
It's just as easy to use <cfdump> on a complex object as it is on a simple variable. Therefore, to give you a better idea of how <cfdump> can help you visualize your objects, I will use a query object for this example.
First, lets create a query object. We do this with the <cfquery> tag:
A <cfdump> of the above query would like something like this:
| query | ||||
|---|---|---|---|---|
| FIRSTNAME | INDIVIDUALID | LASTNAME | USERNAME | |
| 1 | Fred | 1 | Flinstone | freddo |
| 2 | Homer | 2 | Simpson | homey |
| 3 | Homer | 3 | Brown | notsofamous |
| 4 | Ozzy | 4 | Ozzbourne | Sabbath |
| 5 | Homer | 5 | Gain | noplacelike |
The <cfabort> Tag
It can sometimes be handy placing a <cfabort> tag immediately after your <cfdump>. This way, you prevent the application from doing any further processing until you've decided whether the results of the <cfdump> are correct or not. If you decide the results of the <cfdump> are correct, you can continue to step through the page, placing <cfabort> (and/or <cfdump>) at logical points so that you can get a "snapshot" of the state that the application is in at a particular point.
Debugging Settings (via ColdFusion Administrator)
The ColdFusion Administrator provides a number of debugging options for developers. You can find these options under the DEBUGGING & LOGGING heading on the left menu. The first option is Debugging Settings. This allows you to specify what debug info should be displayed and how.
The next option on the left menu lets you restrict the debug output to specific IP addresses if required. This is useful if you are debugging in a production environment and don't want your users to see the debugging output.
Below are the options available in the Debugging Settings option:
- Enable Debugging
- This turns debugging on. Debug info is now displayed when you view the site in a browser. When this option is checked, the actual debug output is determined by the following options.
- Select Debugging Output Format
- You can choose whether the debug info is displayed at the bottom of the page (classic.cfm) or in a popup window (dockable.cfm).
- Report Execution Times
- This option allows you to see how long each ColdFusion file takes to execute. This includes templates, includes, modules, custom tags, and compoment method calls. A useful tool that allows you to isolate slow running blocks of code very quickly.
- Database Activity
- When this is enabled, you will be able to see each query as it is being run against the database. Useful if you have dynamic queries.
- Exception Information
- Provides information about any ColdFusion exceptions that are raised during processing.
- Tracing Information
- Allows you to track program flow and efficiency with the
<cftrace>tag. - Variables
- When this is enabled, the debug output will display each variable and its value. You can select which variable scope to report on, or you can choose all scopes if you like.
The following options can be enabled/disabled independently of the above debugging settings:
- Enable Robust Exception Information
- Allows visitors to see the following information in the exceptions page:
- physical path of template
- URI of template
- line number and line snippet
- SQL statement used (if any)
- Data source name (if any)
- Java stack trace
- Enable Performance Monitoring
- Allows you to monitor ColdFusion performance via the Windows Performance Monitor. If the website isn't on a Windows based machine, CFSTAT will provide the same info.
- Enable CFSTAT
- Allows you to monitor ColdFusion performance in real-time via CFSTAT — a command line interface.