CleanCode logo
NAVIGATION: first page in sectionup one levelnext pagefinal page in section


DescriptionDiagnostic engine for software development
LanguageJava, Perl, JavaScript
InterfaceCode Instrumentation
Reference Perl Java JavaScript

Software development is both an art and a science. A good software developer, when presented with a bug, will often be able to know precisely which line of which method of which file of which package of code has the wrong boundary condition on the "while" loop that is causing, say, the pages to come out in reverse order. Particularly during active development of a piece of software, when one is intimately familiar with the code, this will be true a large portion of the time. But 6 months later, when the same developer has handled several other intervening projects, finding the resolution to the very same bug, might take hours and hours of investigation, be it code-reading, running test cases, editing the code to test scenarios.

That is the best case scenario, of course. Then there are the cases of asking a developer who has never seen the code to identify the bug, or asking a less-experienced developer. And there's the nature of the bug itself. What if it manifests with some data, and not with other data? What if it is intermittent--with apparently the same data it manifests sometimes and not others?

Integrated development environments (IDEs) go a long way towards helping track down an elusive bug. Being able to set breakpoints, examine variables, step through code, etc., are vital and useful capabilities in an investigation. For many things, that may be all you ever need. But what if you need to run a program for an extended period to manifest a condition? Or what if, after making a change, you want to run a regression test and examine a program's internal state all along the way (say hundreds of data points)? Or what if you have a web application and wish to debug its server interactions -- from the browser itself? This is where DataDiagnostic comes in. Here is a sampler of what it can assist with;

view list -- click for full size

The series of illustrations will illuminate some of these. Select the illustration to enlarge it to full size. The first one is our baseline. A web applications showing a normal, user display. (CleanCode aficionados will recognize this as a screen shot from the Server File Explorer application.) DataDiagnostic is available in Perl, Java, and JavaScript--all the languages I currently use on a regular basis, because it is so handy (to me:-). For demonstration purposes, I will use this web application focusing on server-side diagnostics. DataDiagnostic could just as readily be used to show client-side diagnostics (though Server File Explorer does not have any significant JavaScript to warrant it) or for Java or Perl standalone applications.

standard version diagnostic -- click for full size

Beginning with this illustration, you'll observe a sampling of the diagnostic output that one may obtain via the command-line--in this case the command-line is the browser address bar. The DIAG_LEVEL variable sets a value for the diagnostic mask, where each bit controls some aspect of diagnostic output. Here we have set a single bit that activates the built-in VERSION_DIAG, which, as the name implies, identifies versions for all instrumented modules.

Observe the bottom of the window, where the diagnostic output is displayed between the two heavy black bars. Four modules (Perl modules in this case) have been loaded on the server to generate this output. Say, for example, that you are releasing a new version of your web application and your test team reports that something that was supposed to be fixed is still not fixed. One of the first things to do is check if all the version numbers are correctly indicating the versions you expect. And you can do this without leaving the comfort of your browser (since in many cases, the web server code is not easily accessible to the developers--for good reason!).

standard environment diagnostic -- click for full size

So you have verified the correct module versions are installed. Another important question that is easily overlooked: has there been any environment changed that was not expected? This illustration shows another built-in diagnostic axis (ENV_DIAG) that displays the current operating environment, including separate tables for server variables, cookies, and command-line parameters. Here you see just the beginning portion of the server variable table, nicely formatted.

Incidentally, the Server File Explorer application shows the diagnostics at the bottom of the web page, following the regular content. DataDiagnostic is configurable to position the diagnostic output wherever you like on the web page.

diagnostic level missing -- click for full size

Another built-in axis, TRACE_DIAG, allows you to trace program flow through any procedures, functions, or methods that you have explicitly instrumented. Now this particular application, Server File Explorer, has defined values for ENV_DIAG and for VERSION_DIAG, so knowing the values for those, we were able to set the diagnostic mask to those values to turn on their output. But Server File Explorer does not define TRACE_DIAG, because I did not think it was needed at the time. Hence, in this illustration, you'll observe that using the hex value of 0x80 presents no diagnostics, because that value has not been set in the program. But the story does not quite end there...

dynamic diagnostic level added -- click for full size

Many moons later, I'm thinking I sure wish I could turn on that diagnostic axis... but wait! This is DataDiagnostic, so I can just define it and turn it on--from the command-line itself. If you expand this illustration to full size, then, you'll see that not only is DIAG_LEVEL specified on the command line (address bar), but I have simply set TRACE_DIAG to the very same value, and voila, some not terribly exciting output, but you get the idea...

This series of illustrations shows diagnostic output in HTML format. DataDiagnostic may be configured to use any of a selection of channels -- HTML to stdout, text to stdout, text to stderr, data format to log file. And you may send to multiple channels at the same time.

user-defined mask level -- click for full size

The preceding illustrations have shown several of the pre-defined diagnostic axes available. But DataDiagnostic allows you to define your own as well. The Server File Explorer application happens to define just two, one to display global information and cookie processing, and one for file processing actions. But you may specify as many as you like to achieve as fine a resolution as your needs demand. This illustration has turned on one of these two user-defined levels.

combining mask levels-- click for full size

For discussion purposes, we have shown individual diagnostic levels in each of the preceding illustrations. But remember that the DIAG_LEVEL command-line parameter is a bit-wise mask. You may turn on any combination of bits you wish to see multiple diagnostic levels output as they occur. To aid in visually compartmentalizing the results, each level is color-coded (via CSS) so you can still focus on elements of interest. This illustration shows the same user-defined diagnostic from the last example, combined with the VERSION_DIAG shown earlier.

Go to Perl tech docs Go to Java tech docs

Valid XHTML 1.0!Valid CSS!Get CleanCode at Fast, secure and Free Open Source software downloads
Copyright © 2001-2013 Michael Sorens • Contact usPrivacy Policy
Usage governed by Mozilla Public License 1.1 and CleanCode Courtesy License
CleanCode -- The Website for Clean DesignRevised 2013.06.30