Not Just the Facts

A wide variety of information can be included in a log. Table 14-2 details some of it according to the categories described in the previous section. As you look at this table, keep in mind that Murphy's Law really applies here. Specifically, you may not know what you need in a log until you need it, so try to create log data with enough context to make sense of what is happening. In other words, if you are logging information about a complex transaction, don't just log when the transaction started and stopped : log each processing step so that you can understand transaction states. As an alternative, use an approach common in rule-based systems, in which the system should be able to "explain" its behavior.

Log data may be provided in real time, or nearly real time, to other applications. This will help you create such things as dynamically updated dashboards that show the status of the system in a rich graphical format.

Table 14-2. Techniques to Improve Log Utility

Category	Suggested Contents
Debugging/Error Logs	Contextual information. Consider the following entry (from an MS Windows Dr. Watson error logging program(DrWtsn32)). *----> System Information <----* Computer Name: LUKELAP User Name: Luke Hohmann Number of Processors: 1 Processor Type: x86 Family 6 Model 6 Stepping 10 Windows 2000 Version: 5.0 Current Build: 2195 Service Pack: None Current Type: Uniprocessor Free Registered Organization: Registered Owner: Luke Hohmann Inputs and outputs to each function call or equivalent. Consider multiple debugging levels and whether or not you should record parameter values. Recording parameter values takes some planning because you can't simply dump complex data structures into a log file and expect it to be useful. Serializing these data into XML is a good choice, but you have to be careful about how much data you're adding to the log and how much of a performance hit you'll take in the process. This issue is so complex that you probably won't be able to establish a uniform policy but will instead have to approach each log entry on a case by case basis. All main componentsfor example, in a heavy client client/server system both the client and the server.
Performance Tuning	Each command and how long it took to execute. If possible, track both elapsed and actual processing times.
Capacity Planning	Complex systems use a variety of resources. Monitoring usage levels in log files allows you to tune performance. In one application I worked on, the system administrator could specify the initial number of database connections in a configuration file. During operation, the system would create additional connections as needed. By recording the number of connections used as well as any connections that were created in a log file, we provided system administrators with the data necessary to tune their performance. If they specificed 50 initial connections but never used more than 30, they could lower the number and improve performance by freeing up valuable resources. If they specified 50 initial connections and consistently required 80, they could increaes the initial number of connections, again improving overall performance (because creating the connections at startup is faster than creating connections on the fly).
Behavior Tracking and Auditing	Reports of operations/features used, including optional features not used. For example, it is easy to add information to a log file when an optional feature structured as a DLL is invoked. Scanning the log to identify if these features are invoked at all is trivial. Highly used features may be sources of new revenue by creative licensing programs, including feature-based licensing. Unused or little used features may be removed in a future release or may become the target of marketing and/or educational campaigns designed to increase use. Logs used for auditing purposes must be trustworthy.
System Configuration Input and Processing	Data in configuration parameters. If any are processed by your system in an interesting and useful way, add the input and the resultant output or effect to a log file. Many inappropriate configuration parameter values can be overridden by the system. Any resets should be logged for further review and analysis.
Operational Status	Operational status logs, being most closely associated with enterprise server applications. These applications have specific status requirements. Transaction-based systems may log transaction states (beginning, processing, ending), cumulative requests, outstanding requests , and so forth. Enterprise applications based on concurrent user business models may log logins and logouts, graceful or abrupt session termination, failed login attempts, or total number of users, etc. Operational status logs often correlate to the business model.

Logs Are Not Glorified Trace Statements!

Once the decision has been made to create any log files, developers usually start stuffing a variety of them with data that is generally useless to anyone but them. To maintain coherence and integrity, especially of logs used by customers and/or technical support organizations, and to meet the team's legitimate debugging needs, I recommend a separate log for developer-centric data. Once this is done the tarchitect can periodically review the contents of a sample log and work with developers to see that the right data ends up in the right log.