Using ColdFusion MX's Debugging Options

ColdFusion MX offers you some extensive debugging and error?handling features. There are quite a few, and to the person new to ColdFusion, it is natural to wonder where to start. The place to start is the Debugging settings of the Administrator Page (see Figure 19.1).

Figure 19.1. Ground Zero for debugging in ColdFusion MX is the Administrator Debugging settings.


The ColdFusion MX Administrator Debugging Settings

This page enables you to customize exactly what appears in the debugging output. You can also use it to monitor the ColdFusion MX server. To customize your debugging settings, follow these steps:

  1. Select Start, Macromedia ColdFusion MX, Administrator, or if you are using a Mac (or any J2EE capable system), enter a URL to the cfusion admin, such as http://your-computer.local:8080/cfusion/.

  2. When the login page opens, enter your password.

  3. When the Administrator page opens, select Debugging Settings in the Debugging and Logging section on the left side of the page. This will open the Debugging settings page.

When the page opens, you will be presented with a number of options. They are:

  • Enable Debugging: Click this to enable or disable debugging. Debugging, as you will notice, is turned off by default. If you are using Flash Remoting, having debugging enabled is almost mandatory.

  • Select Debugging Output Format: You have two choices in the pop-down. The first, classic.cfm, appends the debugging information to the end of a web page.

    This has been a feature of ColdFusion since version 1, which explains the name. The second option, dockable.cfm, is new to ColdFusion MX. It is a DHTML-based interface, which displays the information in a tree view in a separate pop up window that can even be docked to the page. Keep in mind that if you are using pop-ups in ColdFusion, they can be an issue. If you are using a browser or tool that kills pop-up windows, including Netscape, Opera, and the Google Toolbar 2.0, you should turn that option off.

  • Report Execution Times: If a page has a slow response time, this option will show you. Simply enter a value, and any page exceeding it will be highlighted in red. This option is selected by default, and you can choose a summary or a detailed tree-based display.

  • Database Activity: Check this option to enable reporting of SQL database activity.

  • Exception Information: Selecting this, the default, causes any exceptions in a request to be reported.

  • Tracing Information: Selecting this, the default, displays an entry for every CFTRACE tag in the application.

  • Variables: Selecting this causes the ColdFusion variables to be displayed. This is selected by default, and you can choose which variables are displayed.

  • Enable Robust Exception Information: Select this if you are an absolute control freak. The list shows you what will be displayed, and the results will be detail-intensive.

  • Enable Performance Monitoring: If you are using Windows NT or Windows 2000-based servers, check this to enable the standard NT performance counters that display information about the ColdFusion Application server. This is deselected by default. If you do enable it, you will see a graph of the counters available.

  • Enable CFSTAT: For non-Windows servers, select this to take the place of Performance Monitoring. You won't get the neat Windows graph, but you do get the same information.

The Debugging IP Addresses Page in ColdFusion MX

This option only displays debugging messages to local users (who use the local IP address 127.0.01). Instead of turning off debugging output across the board, you can use this window to specify which people in the team see the debugging messages. To use this feature, do the following:

  1. Select the Debugging IP Address in the Debugging and Logging list on the right. The page shown in Figure 19.2 will appear.

    Figure 19.2. The Debugging IP Address page lets you limit debugging messages to specific IP addresses.


  2. Enter an IP address that should be receiving the messages and click the add button.

  3. To remove an address, select it from the list and click the Remove Selected button.


If you don't want to be constantly receiving debugging messages on your local machine, you can delete your address. If you want to add it at a later date, simply click the Add Current button.

ColdFusion MX Logs

ColdFusion MX creates some pretty detailed log files that are an immense help for monitoring and debugging applications. The logging settings page, Figure 19.3, lets you control how ColdFusion MX will maintain the log files and even add a couple that aren't a part of the default. To configure your Log settings, select Logging Settings from the list under Debugging and Logging. The Logging settings page will open.

Figure 19.3. The ColdFusion MX Logging Settings enable you to configure the application's logs.


The settings on the page are:

  • Log Directory: This is the address for the logs. The default is to store them in the ColdFusion MX root directory.

  • Maximum File Size: Log files can get really big…really fast. Use this option to set the maximum file size. When it is reached, the file is copied into a log.archives file.

  • Maximum Number of Archives: If you don't want a couple of hundred logs cluttering up your hard drive, enter a number (the default is 10), and the oldest archive will be deleted when the number of logs exceeds the number entered.

  • Log Slow Pages: Select this to track pages that take longer than the specified amount of time to execute. The primary use for this is to identify bottlenecks in the application.

  • Log All CORBA calls: An option if you are using CORBA objects (Common Object Request Broker Architecture). In simple terms, CORBA is a standard for creating distributed object infrastructures (which is a book by itself). Select this to have ColdFusion log all CORBA interactions to the server.log file.

  • Enable Logging for Scheduled Tasks: Select this if you are using ColdFusion's built?in task scheduler.

Email from ColdFusion MX

With all these debugging messages and logs, it would be nice to ensure that somebody reads them.

ColdFusion MX has a nifty little feature that enables you to add email notification to server administrators in case of serious problems. To set up an SMTP email server, follow these steps:

  1. Select Mail Server from the Server Settings area. This will open the Mail Settings page, as shown in Figure 19.4.

    Figure 19.4. The Mail Server Settings enable you to set up ColdFusion MX to talk to your email server.


  2. Enter either a domain name or an IP address for your company's outgoing (SMTP) mail server.

  3. Enter the Mail Server's port number in the area indicated. The default is 25 because this is almost always the port number used.

  4. If the server is slow, you can adjust the amount of time ColdFusion waits when trying to connect. You can set the amount in the Connection Timeout box.

  5. Enter an amount in the Spool Interval settings to specify how long ColdFusion waits before checking to see if a new email message is waiting to be sent. The lower the value, the sooner they are sent.

  6. Select the Verify Mail Server Connection box to have ColdFusion test the connection settings. Always have this selected.

  7. The Mail Logging settings in the pop-down enable you to choose to log the email generated by ColdFusion by severity or to simply log all the email sent.

  8. Click the Submit Changes button to save the changes.