Using the cftrace tag to trace execution

The cftrace tag displays and logs debugging data about the state of your application at the time the cftrace tag executes. You use it to provide "snapshots" of specific information as your application runs.

This section describes the following topics:

• About the cftrace tag
• Using tracing
• Calling the cftrace tag

About the cftrace tag

The cftrace tag provides the following information:

• A severity identifier specified by the cftrace tag type attribute
• A timestamp indicating when the cftrace tag executed
• The time elapsed between the start of processing the request and when the current cftrace tag executes.
• The time between any previous cftrace tag in the request and the current one. If this is the first cftrace tag processed for the request, the output indicates "1st trace". ColdFusion does not display this information in inline trace output, only the log and in the standard debugging output.
• The name of the page that called the cftrace tag
• The line on the page where the cftrace call is located
• A trace category specified by the category attribute
• A message specified by the text attribute
• The name and value, at the time the cftrace call executes, of a single variable specified by the var attribute

A typical cftrace tag might look like the following:

<cftrace category="UDF End" inline = "True" var = "MyStatus" 
text = "GetRecords UDF call has completed">

You can display the cftrace tag output in either or both of the following ways:

• As a section in the debugging output To display the trace information in the debugging output, in the Administrator, select Tracing Information on the Debugging Settings page.
• In-line in your application page When you specify the inline attribute in a cftrace tag, ColdFusion displays the trace output on the page at the cftrace tag location. (An inline cftrace tag does not display any output if it is inside a cfsilent tag block.)

The cftrace tag executes only if you select Enable Debugging on the ColdFusion MX Administrator Debugging Settings page. To display the trace results in the debugging output, you must also specify Tracing Information on the Debugging Settings page; otherwise, the trace information is logged and inline traces are displayed, but no trace information appears in the debugging output.

Note: When you use in-line trace tags, ColdFusion sends the page to the browser after all page processing is completed, but before it displays the debugging output from the debug template. As a result, if an error occurs after a trace tag but before the end of the page, ColdFusion might not display the trace for that tag.

An in-line trace messages look like the following:

The following table lists the displayed information:

ColdFusion logs all cftrace output to the file logs\cftrace.log in your ColdFusion installation directory.

A log file entry looks like the following:

"Information","web-29","04/01/02","13:21:11","MyApp","[501 ms (1st trace)] [C:\CFusionMX7\wwwroot\MYStuff\mydocs\tractest.cfm @ line: 14] - [UDF End] [MyStatus = Success] GetRecords UDF call has completed "

This entry is in standard ColdFusion log format, with comma-delimited fields inside double-quote characters. The information displayed in the trace output is in the last, message, field.

The following table lists the contents of the trace message and the log entries. For more information on the log file format, see Logging errors with the cflog tag.

View comments in LiveDocs