Note: This blog post is from 2006. Some content may be outdated--though not necessarily. Same with links and subsequent comments from myself or others. Corrections are welcome, in the comments. And I may revise the content as necessary.
While the first 3 entries in my FusionDebug series
of posts have been making the case for using the tool, the fact is that like any tool there are tips and traps that you'll do well to note. In this entry, I share several of these from my experience. First I'll share a few tips on using the tool, then a few on setup of the tool.
Tips and traps on Using the Tool
Favor "Step Over" versus "Step Into", when on tags/functions that don't open files
As you are at a breakpoint about to step to a new line of code, I'll recommend that you use "step over" in favor of "step into". The latter should be used only on tags like CFINCLUDE, CFINVOKE, CFC method calls, and other tags/statements that would open a new file. It allows you to follow the flow of control into that new file (opening it, and stopping at the first line of code within that file.)
Why would I recommend you do not use it on other tags and statements? Well, recall that CFML is built on Java underneath. I've found that sometimes "step into" will cause the Eclipse debugger to take a longer time while stepping through the underlying Java of a given tag or statement. Also, some CFML tags are built in CFML.
FusionDebug doesn't show you the underlying lines being stepped over in such Java or CFML files (it's configured not to by default), but the execution will take longer than if you had used "Step Over". I've found the problem happen with tags like CFDIRECTORY and CFDUMP as well as createobject() and findnocase(). When it happens, things will just seem to be hung, but be patient.
I'm stepping, but nothing happening
Related to the above, if you are doing stepping and things seem hung, for whatever reason, with nothing seeming to happen, watch for the term "Stepping" in the Stack Trace pane (at top right). That just means that it's working, and taking some time to do whatever you've asked. Simply be patient. Control should come back.
"I don't see the 'current instruction pointer' moving while stepping"
This is quite a gotcha, which threw off myself and the FusionDebug guys. In one circumstance, as I hit the "step over" and "step into" buttons, nothing seemed to be happening. The "current instruction pointer" wasn't changing. I thought it wasn't stepping at all.
I looked at the "stack trace" pane, and rather than show "stepping", it did indeed show that the execution was proceeding from one line to the next as I'd hit the buttons.
It turned out to be a problem related to my having opened the file using the file system, rather than via an Eclipse "Project". The docs explain how to open files "properly". Forewarned is forearmed.
Be careful holding breakpoints within CFLOCK or CFTRANSACTION tags for too long
You may not think of or notice this, but if you hold a breakpoint or do stepping within tags like CFLOCK or CFTRANSACTION, you could have a negative impact on other users in your environment.
In the case of CFLOCK, you could keep someone else (who's trying to obtain that lock) from being able to get that lock.
In the case of CFTRANSACTION, you could keep someone (even outside of ColdFusion) from being able to read or update the database you are updating within the CFTRANSACTION. The degree of impact will be influenced by the ISOLATION attribute you use (or its default) in the CFTRANSACTION.
If a runtime error occurs, FD will also seem to stop
Something to keep in mind is that if you find FusionDebug just seem to stop debugging, the problem may be that you've hit a runtime (or even compile time) error in the code, which will cause CF to send an error screen to the browser but will not send anything to the debugging stream that FusionDebug is watching. As such, FusionDebug will just lose its connection to the running program.
If debugging just stops, CFMX admin's "request timeout" may be killing the page
It's easy to forget that when you're in the midst of a debugging session, you're causing the page to take likely several seconds (perhaps even minutes) to run to completion. Recall as well that CFMX has an admin setting called "Timeout Requests after x seconds" which if enabled will cause ColdFusion to detect and halt a page if it takes longer than that time to execute.
Naturally, if it is enabled and you debug a page for longer than that duration, ColdFusion will intercept the request and send an error to the browser. In that regard, this is similar to the previous issue.
Something to noticed, however, is that this "timeout requests" setting is not enabled by default in CFMX 6.1, while it is enabled by default in CFMX 7. As such, this problem of timeouts will more likely happen in CFMX 7, though again either can be configured to support it. Just be aware.
You could also override this timeout setting in a given page by using the CFSETTING tag with its RequestTimeout attribute. (You can of course also affect an an entire application by placing that in the application.cfm.)
If breakpoints fail to fire as expected
If you have any other sort of problems with breakpoints firing, note that the FusionDebug folks have written a tech support article on the topic.
Tips and Traps on Setup
Beware of the impact of debugging on shared servers
Though you certainly can turn on debugging against a central shared server (such as test, staging, or even production), you should be aware of the potential impact.
As has been discussed before, when any user requests a page that's being debugged and their execution would hit a breakpoint, the page will appear to them to be hung until the debugging developer steps through the code to completion.
Beware of the impact of the JVM config changes
As discussed in the FusionDebug User Guide, in the section on setting up tool, one of the changes you make in the jvm.config file is to remove the UseParallelGC option. That change in the garbage collection process could have an impact on the running of the server.
This is one more reason to think twice about running the tool on production.
Understanding the "ports"
When you configure that jvm.config entry, another modification is to name the port that you want the JVM debugging feature to broadcast on. Of course, you want to point to a free port when you name that (you can use "telnet servername portnumber" at the command line to determine if a port is free).
But another point to note is that this port is NOT something you then use when you request pages, nor should it be specified as the value of your web server. Instead, this port number is then used when setting up the FusionDebug interface within Eclipse. All this is well explained in the User Guide.
Using FusionReactor? (Intergral's CF monitor tool)
If you are using FusionReactor, which is Intergral's CF monitoring tool, be sure to disable its "crash protection" feature, while doing debugging. The two features are not compatible.
Those are a few gotchas. I hope they help you. If you hit others, again, I recommend you check out the FusionDebug web site
. They have the docs, faqs, articles, Captivate videos, and more. Most important, they offer free support at [email protected]