Debugging Server-side Software
June 15, 2001

by Don MacVittie

Anyone who develops software eventually has to debug. Web development is the same as any other form of development in this sense. You will spend more time debugging than you will writing code. This article provides some simple debugging tips that will help you identify the problem(s) quickly so you can get back to developing new code promptly.

Because there are so many variables involved in remote debugging, some assumptions are necessary to make an article of this size useful. This article assumes that:

• Your server is configured correctly.
• There are other articles available to help you set up a Web server for your environment.
• You have Telnet or SSH access to the server. (It is possible to develop Web server applications without this access. But it is nearly impossible to debug problems if they occur only on the remote system and you do not have access.)

The following are some common tips for debugging server-side Web applications:

• Develop locally; deploy remotely. Don't debug remotely unless you must. Debugging on a remote machine adds variables to the debugging process such as the quality of your connection and your rights on the remote machine. It is important that you test on the target machine, though. The best developed software can break when it is moved to a new environment.
• Log everything to file. Java Servlets, JavaServer Pages (JSP) technology, and languages used with the Common Gateway Interface (CGI) allow you to open and write to files. Make a routine that opens a file on disk, writes out a message, and closes the file. This will significantly slow response times, but if you only use the routine when debugging, that should not be a problem. While debugging, intersperse calls to this routine all through your code to see where it breaks, and write out relevant values once you've found where, but don't know why.
• Use the page you are generating to get debugging information. Once you write out a header, then you can write data to the page. Write the page header out first (or configure your Web server to assume the page header is based on script type), then you can place your error messages right in the page. This is the simplest way to generate debugging output, and it should be fairly obvious if you forget to remove any output statements before final testing.
• Say it with cookies. If you want to see your normal program output while debugging but need to look at values also, set cookies with the name of the variable you're interested in and the value. Then you can look at the value of cookies in the browser to see what the state of your chosen variables are.
• Know where you are deploying. If you receive 404 (file not found) errors when attempting to view your program's output, put an HTML file in the directory and try to load it. You may not be where you think you are, and this technique will show whether you can load a simple Web page from your current location. Also, make sure you can load another application from the same location.
• Configure your server correctly if you see source code. Make sure the Web server is set to recognize your file's extension as a script. If you are seeing source code, chances are likely that the server is not configured correctly. In some languages, if a part of your page displays correctly and a part of it shows up as code, you have an unclosed quotation mark somewhere. So do not assume that your server is misconfigured unless the entire page is showing source code.
• Do not play with stderr (standard error). There are three default files in many programming languages -- stdout (standard output), stdin (standard input), and stderr. In Web development, stdout goes to the page, and stderr goes to the console or nowhere. Common practice is to redirect stderr to stdout (for example, the error stream to the HTML page) while debugging. Don't do it because you will eventually forget to do cleanup, and a user will be faced with a browser full of cryptic messages. Remember that you will always write to stdout, but if all is running well, you will not write to stderr. You can test and have all run well, but then six weeks later a customer can hit a problem and get a dump of debugging information meant for you. If you need to capture stderr, capture it to a file where it is safely away from users. You still need to clean up, but if you forget to do so, this will not affect your users.
• Make certain you're getting the most recent version of your page. JSP pages and Perl scripts are compiled at the time they are accessed by a user. In some Web servers they are compiled and cached to enhance performance. Make a minor but obvious change to your script and then reload it in your browser. If the page does not reflect your change, you are not recompiling your script. Find out how to flush the cache or force a recompilation on your Web server.
• Validate your server's access to back-end machines. If you are using a database technology and your script requires access to your database, make sure you have reliable access to that machine. With most technologies, it will be clear you have lost access when you use the other techniques defined in this article, but this one is still worth mentioning.
• Choose your development tools with an eye to debugging. Some very powerful development environments do not have very good debugging support. Since you are likely to write an application once and debug it many times, it makes no sense to use a tool that does not help you debug at all. PHP is an example of a language that doesn't support debugging well. Do a little work upfront to choose the right tool -- this will save you many hours in debugging time.

CGI Tips

• Make certain your scripts are executable. Whether they admit it or not, every script developer has spent a lot of time debugging this error at least once. If the file is not executable, you get an error message.
• Use Strict to make sure you know what values your variables hold. In Perl, use the Strict compiler directive when compiling your code. Among other features, Strict requires that you declare all variables before using them. Many Perl developers do not use the Strict compiler directive, and failure to use it can create subtle errors that may take hours to debug.
• Use your environment's warning mechanisms. Turn warnings on to a reasonably high level. In the current Perl manual under bugs, you will find "The -w switch is not mandatory" listed as a bug. Warnings are there to let you know you're shooting yourself in the foot. Ignore them at your own risk. This is true no matter what language you are using. Some warnings not reported by the default settings of your C compiler may in fact be errors in a Web development environment.

Tips for Java and JSP Technology, and Servlets

• Use Java Platform Debugger Architecture tools when possible. Utilize a development tool that supports this debugging environment. Doing so will simplify remote debugging and let you debug right in your integrated development environment (IDE) or from your debugger.
• Save information about every exception. Print every exception description you catch somewhere. Save them to disk, output them to your page, and put this information where you can get to it; it is some of the best error reporting to which you have access. In the purest sense, exceptions are unexpected actions that your program is dealing with. Writing out information about all exceptions will tell you much about what's going wrong. When you are done debugging, you should stop writing about the exceptions (to file), or they will impact your Web server's performance.
• Always print out the stack trace. Save the stack trace caused by unhandled exceptions somewhere, too. It will tell you where problems occurred in your code. If you have an error page configured, turn it off while debugging and you can dump your stack trace out to the page. Don't forget to reenable your error page when you're done debugging, though.

Finally, listen to your intuition. You know where your code is the weakest, and you know what pieces might break. Don't start each debugging effort from the ground up. Rather, look at the problem and see how it fits into what your intuition and experience tell you might be wrong.