Every program should write a log file. Period. Log files will save you hours and sometimes days of tedious debugging work. They are a basic part of structured debugging and quality assurance. The idea might seem odd in these days of application servers, SOA, and the like, but log files are the most efficient and flexible way to debug software and analyze problems. In the first installment of this two-part article, I examine the basics of logging and log files. In Part 2, I'll examine specialized techniques that you can use for multithreaded application or large data sets.
Why Log Files?
In a perfect world, we wouldn't need customer support, debuggers, or log files. In the real world, the more complex things get, the more difficult problems arise. Some will be seen and fixed before a program is in production/released. Others will show up much later and raise thier heads rarely. That's where log files come in.
A log file has several benefits for analyzing a software problem:
- It's simple to create and efficient to write
- It doesn't lie or forget. It's robust.
- It can be transmitted easily by email. It's flexible
When problems arise in software, tech suppoort will usually receive a call or a email about it. It is amazing, how bad, how little, and how confused the information from customers will be about what they have done, what happened, and what the problem is. If your application writes a log file, even if it only contains the used data sources and the executed commands, you will certainly notice that this information often differs from the information relayed by the customer. This will save time and provide clarity--In the same way that a flight recorder often provides the only valid information source to analyze aircraft crashes.
Tech support people can also learn to read and interpret log files and thereby reduce the number of times they need to contact developers. But most importantly: Log files help you in finding bugs that you can't reproduce. Debugging literature general states " make it fail" as a major step (see Chapter 4: Make it Fail in Debugging, by David J. Aagans. Ifyou can't make it fail, then log files are your last resort.
When and Where Do You Store Log Files?
When creating log files you should consider several conditions:
- An application should open the log file at startup and close it just before termination.
- It's important to make sure that a program has write access to the log file's location on all supported platforms. Windows Vista, for instance, is much more restrictive about that than previous versions. The log file should be easy to find and have a name that is self explanatory, such as "AppName".log. The best location is always a folder named "AppName"Logs\ wherever its location is appropriate.
- You might come up with the idea of creating separate log files for separate modules or for different purposes ( a standard log and debugging log, for example). Generally speaking, this is not a good idea. You'll find yourself searching in multiple log files, comparing timestamps, and so on. It's best to use only one log file at a time. That said, separate instances of an application should use separate files as long as they operate independently.
- You might also come up with the idea to log not to a file but to a database. This seems high-tech, but it directly contradicts the key concepts of simplicity, flexibility, and robustness.
What to Log
The first entry in a log file should be something like "starting log" and the last entry should be a statement like "closing log file." If this entry is missing, you know that the application terminated unexpectedly.
After this first entry, some general information should be recorded:
- Operating system version, patches.
- Size of RAM installed, size of free RAM available, and free space on hard drives.
- IP address, machine name, username, and so on.
- Current date and time
- The version of your program.
- The version of components, DLLs, and libraries that you use.