Controlling debugging information in CFML

The following sections describe how you can use CFML tags and functions to display or hide debugging and tracing information.

Generating debugging information for an individual query

In the Administrator, the cfquery tag debug attribute overrides the Database Activity setting on the Debugging Settings page. The debug attribute has an effect only when debugging output is enabled on the Debugging Settings page, as follows:

For example, if Database Activity is not selected in the Administrator, you can use the following code to show the query execution time, number of records returned, ColdFusion page, timestamp, and the SQL statement sent to the data source for this query only:

<cfquery name="TestQuery" datasource="CompanyInfo" debug>
  SELECT * FROM TestTable
</cfquery>

The debug attribute can be useful to disable query debugging information generated by queries in custom tags that you call frequently, so that you only see the debugging information for queries in pages that call the tags.

You can also view stored procedure-specific debugging information by specifying the debug attribute in the cfstoredproc tag.

Controlling debugging output with the cfsetting tag

Use the cfsetting tag showDebugOutput attribute to turn off debugging output for a specific page. In the Administrator, the attribute controls debugging output only if the Debugging Settings page enables debugging output. The attribute's default value is Yes. The following tag suppresses all debugging output for the current page:

<cfsetting showDebugOutput="No">

You can put this tag on your Application.cfm page to suppress all debugging output for an application, and override it on specific pages by setting showDebugOutput="Yes" in cfsetting tags on those pages. Conversely, you can leave debugging on for the application, and use the cfsetting showDebugOutput="No" tag to suppress debugging on individual pages where the output could cause errors or confusion.

You can also use the showDebugOutput attribute to control debugging output if you do not have access to the ColdFusion Administrator, but only if the Administrator enables debugging.

Using the IsDebugMode function to run code selectively

The IsDebugMode function returns True if debugging is enabled. You can use this function in a cfif tag condition to selectively run code only when debugging output is enabled. The IsDebugMode function lets you tell ColdFusion to run any code in debug mode, so it provides more flexibility than the cftrace tag for processing and displaying information.

You can use the IsDebugMode function to selectively log information only when debugging is enabled. Because you control the log output, you have the flexibility of silently logging information without displaying trace information in the browser. For example, the following code logs the application page, the current time, and the values of two variables to the log file MyAppSilentTrace.log when debugging is enabled:

<cfquery name="MyDBQuery" datasource="CompanyInfo">
  SELECT *
  FROM Employee
</cfquery>
<cfif IsDebugMode()>
  <cflog file="MyAppSilentTrace" text="Page: #cgi.script_name#,
completed query MyDBQuery; Query Execution time:
#cfquery.ExecutionTime# Status: #Application.status#">
</cfif>

Tip:   If you use cfdump tags frequently for debugging, put them in <cfif IsDebugMode()> tags; for example <cfif IsDebugMode()><cfdump var=#myVar#></cfif>. This way you ensure that if you leave any cfdump tags in production code, they are not displayed when you disable debugging output.

Comments