cftrace

Description

Displays and logs debugging data about the state of an application at the time the cftrace tag executes. Tracks runtime logic flow, variable values, and execution time. Displays output at the end of the request or in the debugging section at the end of the request; or, in Dreamweaver MX and later, in in the Server Debug tab of the Results window.

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

Note: To permit this tag to execute, you must enable debugging in the ColdFusion Administrator. Optionally, to report trace summaries, enable the Trace section.

Syntax

<cftrace 
  abort = "Yes or No"
  category = "string"
  inline = "Yes or No"
  text = "string"
  type = "format"
  var = "variable_name"
</cftrace>

History

New in ColdFusion MX: this tag is new.

Attributes

Attribute Req/Opt Default Description

abort
Optional
No

Yes: calls cfabort tag when the tag is executed

No

category
Optional

User-defined string for identifying trace groups

inline
Optional
No

Yes: displays trace code in addition to the trace summary display.

No

text
Optional

User-defined string or simple variable. Outputs to cflog text attribute.

type
Optional
Information
Matches to the cflog type attribute; displays an appriate icon.

Information

Warning

Error

Fatal Information

var
Optional

The name of a simple or complex variable to display.
Useful for displaying a temporary value, or a value that does not display on any CFM page.

Attribute	Req/Opt	Default	Description
abort	Optional	No	Yes: calls `cfabort` tag when the tag is executed No
category	Optional		User-defined string for identifying trace groups
inline	Optional	No	Yes: displays trace code in addition to the trace summary display. No
text	Optional		User-defined string or simple variable. Outputs to `cflog text` attribute.
type	Optional	Information	Matches to the `cflog` `type` attribute; displays an appriate icon. Information Warning Error Fatal Information
var	Optional		The name of a simple or complex variable to display. Useful for displaying a temporary value, or a value that does not display on any CFM page.

Usage

You cannot put application code within this tag. (This avoids problems that can occur if you disable debugging.)

This tag is useful for debugging CFML code during application development.

You can display cftrace tag output in the following ways:

As a section in the debugging output
In-line in an application page, and as a section in debugging output. If you specify in-line tracing, ColdFusion flushes all output up to the cftrace tag, and displays the trace output when it encounters the tag.

This is an example of a log file entry:

"Information","web-4","04/08/02","23:21:30",   ,"[30 ms (1st trace)]      
[C:\cfusion\wwwroot\generic.cfm @ line: 9] - 
  [thisPage = /generic.cfm]  "
"Information","web-0","04/08/02","23:58:58",   ,"[5187 ms (10)]  
[C:\cfusion\wwwroot\generic.cfm @ line: 14] - [category]
  [thisPage = /generic.cfm] [ABORTED] thisPage "

For a complex variable, ColdFusion lists the variable name and the number of elements in the object; it does not log the contents of the variable.

The following example traces a FORM variable that is evaluated by a cfif block:

Example

<cftrace var="FORM.variable"

  text="doing equivalency check for FORM.variable"
  category="form_vars"
  inline="true">
<cfif isDefined("FORM.variable") AND #FORM.variable# EQ 1>
  <h1>Congratulations, you're a winner!</h1>
<cfelse>
  <h1>Sorry, you lost!</h1>
</cfif>