Developing ColdFusion MX Applications with CFML
Debugging and Troubleshooting Applications

Using debugging information from browser pages

The ColdFusion debugging output that you configure in the Administrator displays whenever an HTML request completes. It represents the server conditions at the end of the request. For information on displaying debugging information while a request is processed, see "Using the cftrace tag to trace execution".

The following figure shows a sample collapsed debugging output using the dockable.cfm debugging output format. The next sections show each of the debugging sections and describe how you can use the information they display.

General debugging information

ColdFusion displays general debugging information. In the classic.cfm output format, the information is at the top of the debugging output. In the dockable.cfm output format, it looks like the following figure:

(In the classic.cfm output format, the section is first in the debugging output and has no heading.)

The general debugging information includes the following values. The table lists the names used in the classic output template view.

Name	Description
ColdFusion	The ColdFusion Server version.
Template	The requested template. (In the dockable.cfm format, this appears in the Page Overview section and is called Page.)
TimeStamp	The time the request was completed. (In the dockable.cfm format, this appears in the Page Overview section and is called Date.)
Locale	The locality and language that determines how information is processed, particularly the message language.
User Agent	The identity of the browser that made the HTTP request.
Remote IP	The IP address of the client system that made the HTTP request.
Host Name	The name of the host running the ColdFusion server that executed the request.

Execution Time

The Execution Time section displays the time required to process the request. It displays information about the time required to process all pages required for the request, including the Application.cfm and OnRequestEnd.cfm pages, if used, and any CFML custom tags, pages included by the cfinclude tag, and any ColdFusion component (CFC) pages. You can display the execution time in two formats:

• Summary
• Tree

Note:   Execution tine decreases substantially between the first and second time you use a page after creating it or changing it. The first time ColdFusion uses a page it compiles the page into Java bytecode, which the server saves and loads into memory. Subsequent uses of unmodified pages do not require recompilation of the code, and therefore are substantially faster.

Summary execution time format

The summary format displays one entry for each ColdFusion page processed during the request. If a page is processed multiple times it appears only once in the summary. For example, if a custom tag gets called three time in a request, it appears only once in the output. In the classic.cfm output format, the summary format looks like the following figure:

The following table describes the display fields:

Column	Description
Total Time	The total time required to process all instances of the page and all pages that it uses. For example, if a request causes a page to be processed two times, and the page includes another page, the total time includes the time required to process both pages twice.
Avg Time	The average time for processing each instance of this page and the pages that it uses. The Avg Time multiplied by the Count equals the Total Time.
Count	The number of times the page is processed for the request.
Template	The path name of the page.

The page icon indicates the requested page.

Any page with an average processing time that exceeds the highlight value that you set in the ColdFusion Administrator Debugging Settings page appears in red.

The last line of the output displays the time that ColdFusion required total time field describe the total time ColdFusion took to parse, compile, and load pages, and to start and end page processing. This figure is not included in the individual page execution times.

Tree execution time format

The tree execution time format is a hierarchical, detailed view of how ColdFusion processes each page. If a page includes or calls second page, the second page appears below and indented relative to the page that uses it. Each page appears once for each time it is used. Therefore, if a page gets called three times in processing a request, it appears three times in the tree. Therefore the tree view displays both processing times and an indication of the order of page processing.

The tree format looks as follows in the dockable.cfm output format:

As in the summary view, the execution times (in parentheses) show the times to process the listed page and all pages required to process the page, that is, all pages indented below the page in the tree.

By looking at this output in this figure you can determine the following information:

• ColdFusion took 10 ms to process an Application.cfm page as part of the request.
• The requested page was tryinclude.cfm. It took 1502 ms to process this page and all pages required to execute it. The other pages took about 1330 (430 + 711 + 191) ms to process, so the code on tryincludme.cfm took about 170 ms.
• The tryinclude.cfm directly called or included three pages, mytag1.cfm, includeme.cfm, and mytag2.cfm.
• The includeme.cfm page directly called or included one page, mytag1.cfm.
• The mytag1.cfm page directly called or included one page, mytag2.cfm
• The mytag2.cfm page takes about 200 ms to process.
• The mytag1.cfm page took about 450 ms to process. This time included the 200 ms for mytag2.cfm, so the code on mytag1.cfm took about 250 ms to process.
• The includeme.cfm page took about 700 ms to process. This time included about 480 ms for processing other pages, so the code on this page took about 220 ms.
• ColdFusion took 70 ms for processing that was not associated with a specific page.
• The total processing time was 1582 (10 + 1502 + 70) milliseconds.

Database Activity

In the Administrator, when Database Activity is selected on the Debugging Settings page, the debugging output includes information about database access.

SQL Queries

The SQL Queries section provides information about tags that generate SQL queries or result in retrieving a cached database query: cfquery, cfinsert, cfgridupdate, and cfupdate. The section looks like the following figure in the dockable.cfm output format:

The output displays the following information:

• Page on which the query is located.
• The time when the query was made.
• Query name.
• An indicator if the result came from a cached query.
• SQL statement, including the results of processing any dynamic elements such as CFML variables and cfqueryparam tags. This information is particularly useful because it shows the results of all ColdFusion processing of the SQL statement.
• Datasource name.
• Number of records returned; 0 indicates no match to the query.
• Query execution time.
• Any query parameters values from cfqueryparam tags.

Stored Procedures

The stored procedures section displays information about the results of using the cfstoredproc tag to execute a stored procedure in a database management system.

The Stored Procedures section looks as follows in the classic.cfm output format:

The output displays the following information:

• Stored procedure name
• Data source name
• Query execution time
• Page on which the query is located.
• The time when the query was made.
• A table displaying the procedure parameters sent and received, as specified in the cfprocparam tags, including the ctype, CFSQLType, value variable, and dbVarName attributes. The variable information for OUT and INOUT parameters includes the returned value.
• A table listing the procedure result sets returned, as specified in the cfprocresult tag.

Exceptions

In the Administrator, when Exception Information is selected on the Debugging Settings page, the debugging output includes a list of all ColdFusion exceptions raised in processing the application page. This section looks like the following figure when displaying information about an exception thrown by the cfthrow tag using the dockable.cfm output format:

The exception information includes information about any application exceptions that are caught and handled by your application code or by the ColdFusion Server.

Exceptions represent events that disrupt the normal flow of an application. You should catch and, whenever possible, recover from forseeable exceptions in your application, as described in Chapter 14, "Handling Errors". However, you might also want to be alerted to caught exceptions when you are debugging your application. For example, if a file is missing, your application can catch the cffile exception and use a backup or default file instead. If you enable exception information in the debugging output, you can immediately see when this happens.

Trace points

In the Administrator, when Tracing Information is selected on the Debugging Settings page, the debugging output includes the results of all cftrace tags, including all tags that display their results in-line. Therefore, the debugging output contains a historical record of all trace points encountered in processing the request. This section looks like the following figure when you use the classic.cfm output format:

For more information on using the cftrace tag, see "Using the cftrace tag to trace execution".

Scope variables

In the Administrator, when the Variables option and one or more variable scopes are selected on the Debugging Settings page, the debugging output displays the values of all variables in the selected scopes. The debugging output displays the values that result after all processing of the current page

By displaying selected scope variables you can determine the effects of processing on persistent scope variables, such as application variables. This can help you locate problems that do not generate exceptions.

The Form, URL, and CGI scopes are useful for inspecting the state of a request. They let you inspect parameters that affect page behavior, as follows:

• URL variables  Identify the HTTP request parameters.
• Form variables  Identify the form fields posted to an action page.
• CGI variables  Provide a view of the server environment following the request.

Similarly, the Client, Session, Application, and Server scope variables show the global state of the application, and can be useful in tracing how each page affects the state of the ColdFusion persistent variables.

Using the dockable.cfm output format

The dockable.cfm output format has several features that are not included in the classic.cfm debugging display, as shown in the following figure of a docked debug pane:

Application page selections

ColdFusion displays two buttons at the bottom of each page, as described in the following table:

Button	Description
Debug This page	Tells ColdFusion to display the debugging information for the selected frame. Refreshes the debug pane if you select it for the current frame (or the application does not use frames).
Floating/Docked debug pane	Toggles the display between a floating window and a pane docked to the left of the selected frame.

Debug pane features

The debug pane has the following features:

• You can expand and collapse each debugging information category, such as Exceptions, by clicking on the plus or minus sign (+ or -) in front of each category heading. You can also expand and collapse each scope data type display in the Scoped Variables section.
• The top of the debug pane displays the URL of the application page being debugged (as identified by the cgi.script_name variable). Click this link to refresh the page and display the debugging information that results. (You can also refresh the page and debugging information by using your browser's Refresh button or key.)
• The debug pane also displays a box where you can enter a page pathname or URL. When you click the Go button, ColdFusion processes the page and the debug pane is updated with the debugging information for the new page.

Copyright © 2002, Macromedia Inc. All rights reserved.

Comments