ColdFusion Debugging

Development tools such as ColdFusion offer a number of helpful utilities that help to solve and avert problems. These problems, or bugs, are systematically isolated in a process known as debugging. Debugging tools look into an application's circuitry. If a template fails or takes an inordinate amount of time to execute, the developer needs to look under the hood and see what is misfiring.

Error messages alone do not yield enough information to solve a problem. Error messages are normally used as a starting point in a debugging strategy.

TIP

As a rule, you should solve problems as soon as they occur. No matter how mundane an issue might seem, the ramifications and complexities grow exponentially if a problem is not fixed immediately after it is discovered.

Debugging utilities provide information about performance and inconsistent behavior, but they are most critical in isolating exceptions. Exceptions are events that stop ColdFusion from processing any template. Common exceptions include dividing by zero and placing an equal sign (=) in a <cfif> clause instead of an IS or EQ.

Exceptions that usually cause errors can be handled in alternative ways. This is known as exception handling and is covered in Chapter 26, "Error Handling."

Debugging must be enabled server-wide before any debugging information is exposed. Debugging is enabled and disabled via an option in ColdFusion Administrator.

Accessing Debugging Information

ColdFusion's debugging information can be accessed in three ways:

• Debugging output can be generated along with Web pages and can be appended to the bottom of the generated page (called classic format) or displayed in a separate window, which may be docked if needed. You can switch between classic and dockable views in ColdFusion Administrator's Debugging Settings screen.

• Debugging information can also be displayed within the Macromedia Dreamweaver development environment's Results window.

• Debugging information is also available programmatically at run time by way of exposed application services.

Exposed Information

Every time a ColdFusion template runs, information is made available to the developer. You can expose most of this information by toggling certain debug settings in ColdFusion Administrator. The debug settings provide a list of categories, each representing a type of debugging that can be performed. The variations in the way debugging information is exposed depend on the category. The following sections cover each category of information and how it is exposed.

Report Execution Times

An important part of debugging is locating poorly performing code. This option reports the individual execution time for all modules, includes, and components so as to isolate problem spots. In addition, you may specify an ideal response time; any items that exceed that time will be flagged as such.

General Debug Information

Information about a request, including specifics about the browser and server, can be extremely useful when debugging.

Database Activity

Debugging database-related problems requires knowing what SQL statements were submitted (after any dynamic processing) and what was returned. This option displays the record count, SQL, and execution time for each database query.

TIP

ColdFusion Administrator does not need to be used in order to show query information on a page. ColdFusion supports an alternative method that involves placing the word debug inside a <cfquery> tag, as follows:

 <cfquery name="query" datasource="dsn" debug> 

By placing this toggle inside the <cfquery> tag, debug information is automatically printed to the page, regardless of the debug settings in Administrator.

Exception Information

Enable this option to display all gathered exception information (details about what occurred) in the debug output.

Tracing Information

Developers can use the <cftrace> tag to embed custom debug output within their code. The following snippet displays the contents of the SESSION.loggedin variable along with descriptive text:

 <cftrace var="SESSION.loggedin"          text="Login process complete"> 

Turn on this option to display developer-provided debug output.

Timer Information

Enable this option to turn on support for the <cftimer> tag which can be embedded in pages to perform code performance analysis.

Flash Form Compile Errors and Messages

When developing applications using Flash Forms, enable this option to see Flash compiler messages.

Flash Forms are covered in detail in Chapter 16, "Flash Forms."

Variables

When you turn on the Variables debug option, a list of variables is generated along with the debug output. Up to nine variable types may be displayed, each of which may be enabled or disabled explicitly:

• APPLICATION

• CGI

• CLIENT

• COOKIE

• FORM

• REQUEST

• SERVER

• SESSION

• URL

Other variablesfor example, local variablesare not displayed automatically. These may be output manually if need be, using the <cftrace>, <cfdump>, or manual debugging techniques described below.

Enable Robust Exception Information

As a rule, your users should never see error messages. ColdFusion provides error-handling features to allow the developer to control error handling and error display.

However, error screens sometimes may be generated; when this occurs, the developer can determine what information should be shared. Enable this option to include the following:

• Actual template path

• Template URL

• Code line number and code snippet

• SQL statements

• Data source names

• Java stack trace

TIP

This option generally should not be enabled on production sites, as the information exposed could be of interest to hackers.

Enable Performance Monitoring and Enable cfstat

Performance monitoring is a handy tool for tracking the efficiency of a ColdFusion application under load. It can be helpful when you're deciding whether additional hardware should be used, or whether you need to replace code or components.

A utility named cfstat is provided with ColdFusion as an interface for performance data. In addition, users of Windows NT, 2000, and XP can use the Windows Performance Monitor to access this information. To enable performance monitoring, check the Enable Performance Monitoring option; to enable cfstat, check the Enable cfstat option.

Performance can be monitored in real time through the use of the ColdFusion function GetMetricData(). The function takes one argument, which is the name of the performance-monitoring system that the operating system uses. In Windows, the argument is PERF_MONITOR; in Unix, it's cfstat. The function returns a structure with a number of keys. The keys of this structure match the data exposed through the visual and textual performance-monitoring features:

 <cfset stDebug=GetMetricData("PERF_MONITOR")> <cfloop collection="#stDebug#" ITEM="i">  <cfoutput>The debug info for #i# is #stDebug[i]#</cfoutput><br> </cfloop> <!--- the above will output debug info on a Windows system ---> 

The data exposed through performance monitoring, including the key names returned through GetMeTRicData(), is shown in Table 25.1.

Table 25.1. Data Returned Through ColdFusion Performance Monitoring

KEY	DESCRIPTION
avgDBTime	Average database transaction time
avgQueueTime	Average queue time
avgReqTime	Average request time
bytesIn	Incoming bytes per second
bytesOut	Outgoing bytes per second
dbHits	Database hits per second
InstanceName	Instance name of the ColdFusion service
pageHits	Page hits per second
reqQueued	Number of queued requests
reqRunning	Number of running requests
reqTimedOut	Number of timed requests

Access to Debug Information

Debugging information should not be made available to all users. ColdFusion allows you to restrict access to debug information by the IP address that the requests are coming from. The allowed IP addresses are specified in the Debugging IP Settings screen in ColdFusion Administrator.

If no IP addresses are listed, debugging information will be published to all clients. This is generally not what you'd want, so make sure that at least the localhost address (127.0.0.1) is always listed.