One of the new features being provided in ColdFusion MX to aid developers in the debugging of their applications is the CFTRACE tag.
With the CFTRACE tag, you can trace the execution of your application at a variety of levels. Depending on where you choose to place the CFTRACE tag within your application, you can use it to log the execution of particular pieces of code, provide timings for certain sections of CFML that you expect might be problematic, display the contents of variables at various points in the processing of your pages, examine contents of a variable prior to performing a specific function, and engage in many other useful debugging techniques. It all depends on where in your code you choose to use the tag itself.
CFTRACE enables you to peek at what the ColdFusion engine is doing as it processes your code. To demonstrate this concept, let's have a look at a simple example. Suppose we create a simple form that enables users to enter their names. After a user submits his or her name, we want our output page to say "Hello Name!" In addition, prior to displaying the name that the user entered, we are going to convert the entire string to uppercase, using the UCase( ) function. This is easy enough to accomplish, but it gives us a good chance to take a simple look at how you can use CFTRACE.
First, let's examine the simple code used to create the form:
<html> <head> <title>Form Submission</title> </head> <body> <FORM ACTION="form_action.cfm" METHOD="post"> Please enter your name:<INPUT TYPE="text" NAME="Name"> <BR> <INPUT TYPE="submit" NAME="Submit" VALUE="Submit"> </FORM> </body> </html>
Now, if we save this code as form.cfm and run it, our output should look something like Figure 14.3.
Figure 14.3. Output of form.cfm.
Now let's look at the code for our action page. Notice the locations in which I have placed the CFTRACE tag and the comments I've made at each trace point. They enable me to trace the logic flow as my page executes:
<!--- display what form variables were passed from the form.cfm page ---> <cftrace var="form" inline="yes" text="initial form tag"> <!--- change the name passed so that the whole name is uppercase ---> <cfset newname = ucase(form.name)> <!--- use cftrace to see if my function worked ---> <cftrace var="newname" inline="yes" text="upper case conversion"> <br> <cfoutput> hello #newname# </cfoutput>
If we save this file as form_action.cfm and then rerun form.cfm, we can see how the entire process works. I'll use the name "John" in the text box on the form.cfm page. After I enter my name and click Submit, the form_action.cfm page with my CFTRACE tags will run, and we see output like that shown in Figure 14.4.
Figure 14.4. Output of form_action.cfm with the CFTRACE tag in use.
Looking at this output, you can see where we've examined the contents of the form variables after they were submitted. The CFTRACE tag conveniently displays for us all the variables that were sent to the action page as part of the form.
Next, we place another trace point right after the conversion of the string to uppercase. Notice how CFTRACE outputs the results of our new variable. At each point in the process, CFTRACE is providing us with timings indicating how long each piece of the page is taking to execute.
This timing and process flow information is an invaluable tool in debugging problematic applications because you can now surround any suspect pieces of code with CFTRACE points to determine exactly what is going on where and how long it's taking each section of code to complete its respective task.
The CFTRACE tag can take different attributes that help you identify the trace point with which you're working and the code that is actually executing.
Table 14.2 gives you an overview of the attributes that are available for use with the CFTRACE tag.
A good thing to remember as you begin to play around with the power of the CFTRACE tag is that you can use it as much as necessary, even in code that's going to production. The overhead on this tag isn't significant, and assuming that you use the inline="No" attribute, the trace information won't be seen by anyone executing your production code unless you've specifically made that possible by allowing their IP to see debugging information through the ColdFusion Administrator on your production server.
ColdFusion MX logs all tracing output to the new log file: cftrace.log. This file is located in the ColdFusionMX/logs directory.