Audiences for Logging

First, recognize that there are different logs for different purposes:

• End user logging:  The primary log for the IT staff and others that use or support your application.  This is the traditional log and if you do nothing else, create this log.
• Developer's Log:  This is a trace/debug log that is designed just for the development team to use, not for end users to understand.
• Performance Log:  Store performance metrics and other information to enable health monitoring of the application beyond just failures and events.  A traditional web server log or windows performance counters fit in this category.

Second, you need to write log messages differently for the end user log vs. the developer log.  The End user log should be treated like a real deliverable, with some log messages part of the requirements of the application itself.  You'll want to have consistency over time here as well - support staff will learn what the healthy and unhealthy patterns to this log are, and that knowledge allows them to respond to problems efficiently.  Because this log is running all the time and may not be stored in a secure location, secured information should never be written to this log.  For example, never write out a raw database connection string (it might contain a SQL User name and password) or an end-user password in the event of a bad password.  I know, that information may be useful, but it'll be a red flag for support staff that isn't worth it.

The End User and Developer's logs are often the same log in the logging system but can be separated out - by severity or category.  The performance log is distinct because its recording entirely different data (typically numeric, analyzed statistically instead of read linearly).  If your logging infrastructure doesn't support separating out distinct logs from each other, see if it supports separation by category or some other means.  If it doesn't, there are likely better options.

Few applications develop a performance log, but you should consider it.  The lowly basic performance log that's built into web servers is the basis of many analytics systems that can tell you a wealth about the performance and profile of your users and what they're doing with the application. 

End User Logging

This is the most important log to put your time into because it's the log that will affect both customer satisfaction with your application and your support costs.   If the folks that support your application can figure out what they need to do or head off a problem from your logs, you won't get a support inquiry, you'll get an upset customer.  What's it going to take?  First, make sure that every message you write satisfies the three rules of end user messages:

1. What Happened?  What event did the application encounter?  Try to avoid developer language like Exception and think about what the exception indicated.  The description should be based on something that an application user could observe or verify and be consistent with the end-user language of the application.
2. What does it Mean?  So your application lost its connection to the database, but will it recover, or do you need to reboot the computer?  Most developers leave out the consequences part of the event, which is very frustrating if you're on the other side of the log.
3. What is the Most Common Resolution?  If the event indicates a problem, what is the most common resolution, if there is one?  Alternately, if it's a severe problem there is no known resolution for, you might recommend reporting it back to the development team.

It's traditional and a best practice to have the end-user log record messages with a severity (informational, warning, or error).  When picking the severity level, do it based on:

1. Informational:  This should be your default.  No action is required, the event is a normal occurrence.
2. Warning:  Something has happened that isn't normal, and may lead to a real problem or indicate a problem, but it may also be OK.  For example, say the data directory doesn't exist and it should - but you can also just recreate it and keep on going.
3. Error:  The event is definitely a problem that should be looked into or may even be terminal.  These messages are the ones you should spend your most time thinking through to make sure they satisfy the three rules above.

You can optionally have one lower level category, such as "verbose" or "debug" or even "Success" (which fits best with the notion of the other three being a status indicator).  This may be a cleaned up version of your developer - level log information.