FusionDebug Tips, Tricks, and Traps

FusionDebug is an easy straightforward tool, but if you leverage the experience of others, you can be even more productive.

Elsewhere in this issue, Jeff Houser introduces the FusionDebug interactive step debugger. I'd like to carry that discussion a bit farther and share various tips, tricks, and traps I've learned from my experience with the tool and that I've gleaned from available FusionDebug resources. I've been using FusionDebug (FD) for a couple of months now and am a fan.

First I'd like to share some general tips that address some common questions or concerns I've observed, broken down into tips on installation and general use. These should help you appreciate the tool's use and how to make the most of its available features.

Then I'd like to share some tricks or features that you may not readily notice that will make the tool still more useful. Finally, I'll share some traps or problems that you may encounter and how to resolve them.

Tips on Getting Started
Why Bother Using a Debugger?
Perhaps the first and most important tip to share is my perspective on why I think FusionDebug is an important tool. I realize that there are some who dismiss it or may simply feel that there's nothing it can do that CFDUMP or CFOUTPUT can't. I disagree and have addressed those concerns in the first two entries in a series in my blog at http://carehart.org/blog/client/index.cfm/fusiondebug.

What If You Have Problems Using or Installing the Tool?
If you have problems using or installing it, you'll find that FusionDebug support is great. The folks at Intergral, who also make FusionReactor, offer free support for the tool at support@fusion-reactor.com.

How Do You Learn About Using and Installing the Tool?
The vendor's site, at www.fusiondebug.com, offers several very useful resources, including a well-done User Guide and Captivate videos showing how to use the tool, all online and free. There are also ample support FAQs and articles on the site to help solve common installation and troubleshooting glitches.

"I Really Don't Want to Switch to Eclipse"
Here's really good news: you don't have to switch to Eclipse. Yes, the tool does run atop Eclipse, as Jeff explains, but you don't have to give up your favorite CFML editor, whether it's Dreamweaver, HomeSite+, or something else. Use those for editing, and fire up Eclipse (and FD) when you debug.

And you don't necessarily have to install Eclipse, as you may already have it installed. Are you using FlexBuilder? That, too, is an implementation of a commercial plug-in atop Eclipse. You could add FD to that. If you do, when you're debugging Flex apps the tool will switch "perspectives" when control passes from the Flex app to the CFML page it calls.

"I Don't Want to Risk Hurting My Current Eclipse Implementation"
On the other hand, you may want to think twice about installing FusionDebug on top of FlexBuilder or even the CFEclipse-based implementation of Eclipse you may have. If you have any concerns about one plug-in hurting another, remember, you can install more than one copy of Eclipse. When you download it from Eclipse.org, it's just a zip full of files that you extract to a directory. It's okay to install it more than once in a different directory.

Along the same lines, another reason not to install FD atop a FlexBuilder install is if you're running the FlexBuilder trial. When it expires, you'll no longer be able to open that version of Eclipse.

Tips on General Use
Does It Just Debug CFM Pages? I'd Like to Debug CFCs and Calls from Flex, AJAX, Web Services, and Such
Great news: it not only debugs CFM pages but CFCs as well. Regardless of whether you instantiate the CFC in CFML or invoke it via Flex, AJAX, Web Services, Flash or Flash Remoting, or CFMX 7's gateways, FusionDebug will intercept the request.

More than that, the tool is savvy enough to recognize that there are special variables inside a CFC or method, and it will show the var (function local scope) and the "this" scopes in the "variables" pane.

Further, when debugging in a CFC method, there will be additional information in the "stack trace" pane. This is the pane (top left as typically configured in FusionDebug) that shows the filename and line number of the line where control has stopped. When control is stopped in a CFC method, this will also show the function name for the method.

Can It Debug CFSCRIPT Code?
Again, for some reason, many seem to have low expectations for the tool and often ask if it can debug code in CFSCRIPT. It absolutely can.

What Does "Step Into" Mean?
"Step into", when used on a line that would go into a new  file such as a CFC method, CFINCLUDE, or custom tag, will open that new file and show the first line of CFML code in that file.

What Does the User See While a Page Is Being Debugged?
When a browser requests a page that's being debugged and has stopped at a breakpoint, it will appear to be hung until the code sends output.

I Want to Be Able to See the Output Being Generated During Debugging
Following on to the previous tip, you may not see the output being sent to the browser while in the midst of processing breakpoints because ColdFusion buffers output until the page completes or the page buffer fills, or a CFFLUSH tag is executed. While it would be nice if the tool offered a pane to see the output as it's being generated, you have a couple of other options if you really want to see the output during debugging. You could insert CFFLUSH tags periodically in the page, or use the available CFFLUSH INTERVAL attribute to cause flushing after a certain number of bytes. Just be aware that, as explained in the CF docs, the browser may not display partial-page output if enough data hasn't been sent or until certain tags are closed (e.g., images, tables, and frames).

Tricks
Moving from tips to tricks, the following are facets of the tool that you may not have thought to expect.

You Can Debug Against More than Just Your Local Developer Edition of CFMX
Most debugging tools work against a local copy of whatever application you're debugging, but FusionDebug can be configured to debug code running on a remote CFML server too such as a central staging or perhaps even a production server. It could even be a remote hosted server. Of course, the server has to be configured for debugging as Jeff explains in his article so it's not a total free-for-all. Still, the feature is a two-edged sword. See my discussion of traps at the end of this article.

You Can Change Variables on-the-Fly
Don't miss the fact that the tool is for more than just watching what's happening. It also offers the option of changing the variables' values on-the-fly. While at a breakpoint or stepping through code, highlight a variable you'd like to set and right-click "Set Variable" to give it a new value. That new value will immediately be set in the currently running request.

Available Shortcuts
Besides using the mouse-based icons and context menus, there are several keyboard shortcuts available. To set a breakpoint, use ctrl-shift-b. To effect the "step over," use F6. For the "step return" command use F7, and for "Resume" use F8.

It's worth noting that the Run menu shows all the other stepping and related commands, so you don't have to use just the icons and keyboard shortcuts for stepping. This makes it clear that the debug commands used in FusionDebug are actually Eclipse commands, so you can learn more about some of these features in the general Eclipse documentation and other resources.

Though not a "keyboard" shortcut, note that you can double-click on a breakpoint in the breakpoints pane and FD will open the file at that specific line. Similarly, when at a breakpoint or while stepping, you can double-click on a file in the "stack trace" (showing the current template and line number on which execution has stopped) and that will jump to the appropriate line too. This can be especially helpful when you're several files deep (perhaps a file has called a CFC method that has done a CFINCLUDE).

Tricks in Variables and Expressions Panes
When viewing the variables and expressions panes, note that if there are a large number of items, you can use the find option to locate a specific variable. With the cursor in the appropriate pane, use ctrl-f or right-click and choose "find." Note the available wildcards, ? and *.

To set a watch expression, you can either highlight it in the editor, right-click and choose "watch expression," or right-click in the expression pane and choose "add watch expression." Finally, you can right-click on an existing expression and choose "edit expression" to change the expression.

If you want to save the value of some variable as shown in the variables pane, notice the "copy variables" option.

Manipulating Breakpoints
After working with the tool for a while, you may start to have a large number of breakpoints show up in the breakpoints pane. A nifty trick is to group them (group their display) by choosing the rightmost icon (or "view action") in its toolbar, the down arrow, and "group by," and then select a value by which to group the breakpoints. Options include grouping them by the file or project in which they appear. Another option is to create "working sets" of breakpoints that are related in some way you define. They can then be grouped by those working sets and you can move the breakpoints around to appear in those working sets.
If you wanted to remove breakpoints for reuse later, you can also right-click in the breakpoints pane and export or import them.

Available Java Detail Mode
When configuring a debug setup (as Jeff explains in the initial install and setup steps), there's an option to "Display very detailed Java information" that causes FusionDebug to interpret variables like Java objects instead. This mode is useful for Java programmers and those wanting to see the internal structure of a ColdFusion request. It's an "expert" feature, so be careful.

Traps: Challenges with Breakpoints and Stepping
Finally, I want to address several things that can trip you up. Some of them are documented in the FusionDebug manual and Web site; others are ones I've found (and since reported) myself.

My Breakpoints Don't Fire as Expected
You may have problems with how you've configured your FusionDebug setup. See the support article at www.fusion-reactor.com/fusiondebug/support-settingUpDebugConfig.html. One of the features mentioned there is an option called "Compile CF page in debug-friendly mode." This is the default but if you have a problem it would solve, you have to recompile the affected templates while you're debug-enabled. That means you need to open and change the file (even if that means just entering a space and removing it) and then save it so that the next request for the page will recompile it.

Another issue is that if you're configuring debugging against a server that's not your local machine, be careful when configuring the "web server folder" in the "connect" tab since the value for the location of the Web server files should be relative to that Web server (not relative to your local machine, such as if you use a mapped drive locally).

Another possible problem is if you set a breakpoint on a line that doesn't contain CFML tags or expressions. Eclipse won't prevent that, but execution won't break on that line.
Relative to that, the breakpoint line numbers are fixed and static. If you change the file to add or remove lines, the breakpoint line number(s) may now be incorrect, which could cause the problem above (or the breakpoint may now be on a CFML line that doesn't execute).

Still other issues are explained at the support FAQ, "Why don't my breakpoints fire" at www.fusion-reactor.com/fusiondebug/support.html#breakpoints4.

I Find That While Stepping into Some Tags and Functions It Seems to Hang
This problem happens if you use "step into" rather than "step over" on certain tags and functions and stems from CFMX's underlying implementation atop Java. Some of the CFML tags and functions themselves call on a large amount of Java code, and since Eclipse debugs Java, it will also debug the Java code underlying these tags and functions. You won't actually see the debugging. You'll just see an indication of "stepping" in the stack trace.

Related to this, some CFML tags are actually implemented in CFML so the debugger wants to debug them too. Fortunately, the tool is smart enough not to take you into such pages to debug them as explained in the support FAQ "Why don't my breakpoints fire" at www.fusion-reactor.com/fusiondebug/support.html#breakpoints4. Again, it will just show "stepping" in the stack trace, and that tag or function may take longer to run when stepping than it would when running normally.

I've seen these issues with CFDIRECTORY, CFDUMP, createobject, and findnocase to name a few. The solution for now is to simply use "step over" instead. Using "step into" really only makes sense on tags that open new files. Perhaps eventually the vendor will solve this for us.

My Attempts to Step Don't Step
There can be a couple of issues here. First, pay close attention to the stack trace pane. Again, this is the top left pane showing the file and line number on which control has stopped. If you don't see the editor reflecting control moving to the expected next line, look to see if the stack trace pane shows the control is still "stepping." This means FusionDebug is still working to run your code.

Another instance where it may not seem to be stepping is when ColdFusion MX sometimes performs optimizations around tags. Try using step into when control is on the line before the tag.

I've found an even more pernicious problem that makes stepping seem not to work. The problem exhibits itself while control is stopped on a given breakpoint. Despite subsequent requests to step through code, no new lines seem to be reached in the file editor, but if you watch the stack trace pane you see the line numbers properly stepping through the code. The problem occurs because you have opened the file using the file system rather than an Eclipse "project."

FusionDebug Is Opening the Wrong Files When I Step into New Files
The previous comment had to do with a problem created when you yourself opened a file, but FusionDebug will also open files when you're stepping through code or when it hits a breakpoint. If you find that it's opening the wrong file, see the support article at www.fusion-reactor.com/fusiondebug/support-wrongSourceFile.html.

FusionDebug Is Asking Me to Pick the Location of the File It's Opening
Related to the challenge of FusionDebug trying to open files, you have the option when configuring the source location (as Jeff describes in the setup steps) of choosing to "search for duplicates." If this feature is enabled, and FusionDebug finds more than one file of the same name in the project's folders, it will prompt you to pick which to use.

This and the previous challenge do argue for keeping your Eclipse projects as small as it can be reasonably set. As tempting as it may be to define a project at your Web site root, where you may have dozens (or more) folders or applications, the problem is that Eclipse may find many files with the same name (such as index.cfm, application.cfm, and so on).

While at a Breakpoint or Stepping, I Find that FusionDebug Loses Its Connection to the Request
There can be a few explanations for this problem. First, if your CFML page experiences an error, then CFMX will return an error page to the browsing user but will no longer provide the debugging information that FD requires. As such, FusionDebug will just stop debugging that request with no indication of the error having occurred.

IMPLICATION OF REQUEST TIMEOUT SETTING
Another common problem, especially in CFMX 7 (though it can happen in 6.1 as well), is that while you are stepping through the code, ColdFusion could time out the request. Many know that the CFMX admin console permits specifying a value labeled "timeout requests after x seconds." This protects the server from excessively long-running requests.

Unfortunately, FusionDebug holding a page during stepping will appear to the server to be a long-running request. If CFMX terminates the request, this will cause FD to lose the connection to the request without any indication.

While CFMX 6.1 has this option, it's disabled by default in the new CFMX installation, while in CFMX 7 it's enabled by default. You can override the page request timeout on a page basis using CFSETTING RequestTimeOut.

Implication of Holding Breakpoint Across CFLOCK and CFTRANSACTION
Although this won't necessarily cause a problem for you, something to be careful of when holding a breakpoint is running code inside a CFLOCK or CFTRANSACTION. Either could negatively impact other threads or users. In the case of CFLOCK, you could hold a lock that could hold up others trying to get the same lock. (Locks are a subject of frequent confusion, but further discussion is beyond the scope of this article.) In the case of CFTRANSACTION, you could hold a lock that holds up others trying to access the database you're processing since CFTRANSACTION (driven by its ISOLATION attribute) can tell the database to prevent other reads or writes during the life of the transaction.

Traps: Challenges on Shared Servers
If you do choose to enable FusionDebug on a shared server, such as a central development, staging, or perhaps even production server (in an emergency), be aware of the following potential traps.

Breakpoints Remain Alive for Any User (Not Just the Debugging Developer) While Debugging Is Active
As discussed above, if a user runs the request while debugging is enabled, the page will appear to hang to the user. Only the developer with FusionDebug open will see that it's stopped on the given breakpoint. For now, there isn't any option in FusionDebug to limit the IP addresses whose requests trigger breakpoints.

When multiple users make a request for a page while it's being debugged and hit a breakpoint, FusionDebug will show a "thread" for each user's request in the "stack trace" pane. If this happens and you want to quickly stop the debugging, you can choose to use the "disconnect" (not "terminate") icon in the stack trace pane. That will stop all debugging in the current debugging session.

On the other hand, another approach would be to use the available "skip all breakpoints" option (in the breakpoints pane) to temporarily disable breakpoints from firing any further for the current debugging user.

Who Can Debug Your Server?
For now, there isn't any option in FusionDebug to limit which IP addresses can initiate debugging. Since debugging is enabled simply by specifying a given port, any user who can issue a request against that server and port (and is running FusionDebug) can conceivably set breakpoints. Of course, they also have to be able to open the file via an Eclipse project to set a breakpoint, so effective file security and firewalls can mitigate this concern. 

What Happens When Two or More Developers Try to Debug a Single Shared Server?
Because of limitations in Java and its debugging mechanism (which FusionDebug is leveraging on our behalf), you can't have more than one debugging session open against a given server at a time. If a developer attempts to start a debugging session when another developer has already started one, the request will be denied. Again, in such cases, this calls for judiciously controlling debugging sessions using the "disconnect" feature to stop debugging when no longer needed.

ColdFusion Doesn't Start After I Configure It for FusionDebug
It could be either of two problems. The simplest is if you've made a mistake in configuring the jvm.config file (Jeff explains what to do in the installation steps). If this file has errors then CFMX won't start. So it would be wise to save a copy before editing it, but if it's too late, just read the installation instructions carefully (or contact FD support).

A second reason can easily occur for those using CFMX Enterprise and its available multiple instance deployment option, where you have multiple CFMX instances on a single box. In this case, if you configure just one jvm.config that's shared among them all, there will be problems. See the support FAQ at www.fusion-reactor.com/fusiondebug/support.html#config2.

Finally, there are various troubleshooting tips in the user manual and support pages at fusiondebug.com.

Conclusion
Well, that's a pretty deep plunge into tips, tricks, and traps. I hope they're useful for you. I've spent nearly half the article on gotchas, but to be honest, many of them can be avoided if you simply read the documentation. But I realize many people won't bother so I've highlighted them to help make you more effective in considering using the tool and getting started with it.

Share your experiences with colleagues but be sure to take any negative ones to the vendor. I've found them to be very responsive.

I really think it makes a great tool for the CFML developer's arsenal. And there's great support behind it - Intergral is no start-up; it's several years old. They're CFML developers committed to making tools and add-ons for CFML developers. Check out the free trial, as well as community and volume discounts.