Logging is a traditional and essential tool that assists in monitoring certain activities conducted by your application, as well as what the users of your application. By creating a a centralized logging service that can be used by your application, you can log all required activity so that debugging can be a less painful process.
These are some of the Best Practices for logging:
- Human Readable – While you may be tempted to create a log of event and errors that can easily processed by a feature inside your application, or even by another custom utility, it won’t always be possible or practical to rely on technology to parse through your logs. Unless you have been writing logs for many years, stick to the simple and make your logs human readable.
- Use Timestamps – Add the current system date and time to each logged event. This gives you invaluable information of the sequence of events, how log each event lasted, etc.
- Use Text Format – In the beginning, log everything to a text file. You might be tempted to log everything to a database table, or save the values in XML, but those all require more effort and can make troubleshooting the log writing process harder, so keep it simple.
- Log Everything – It is easy to assume you just want to log errors, but you probably want to log everything in the beginning. I usually create levels of logging, and allow the user or administrator to set the level of logging unique to that instance. The default might be minimal logging, and allow the user to elevate the logging to verbose logging if they suspect an issue. Or you could default to verbose logging until the program has reached a more stable version so that logging can be reduced down to minimal.
- Single Line – If possible, log the entire event as one line. That won’t always be possible, but it should be your goal to maintain readability.
- Keep it Local – Create an maintain your log files to the local system. How can you log a network issue if you can’t reach the file on a network server?
- Rotate Files – If you program is running over a long enough period, your log files can get very large. If you are writing verbose logs, and you program writes 1 MB of data per day, after one year you might have a 200-365 MB log file. After 5 years you could have a 1 GB log file. Files that large offer very little assistance if you really need to read through them for an actual troubleshooting event. You should decide how long the information is valuable, and either overwrite older events or create a new log file. It is much better to sort through several smaller files to locate the correct file to read than one massive file.
You should consider the following questions when writing your logging solution:
- What happened – Was the event a failed login or a crash? Use plain English (or your local language) and just write in the log what happened.
- What component is impacted by this event – Was it the main executable, a dll, or a 3rd party tool?
- Where did it happen – Was it a network issue, a local server issue, or a failure to access the application database? This will help you know where to start your troubleshooting efforts.
- When did it happen – If you have your timestamp in the event, this will ready help you understand the sequence of events and how they relate to events outside of your program.
- Why did it happen – If your program knows why you got an error or why some processing step couldn’t complete, write it in the log.
- How did it happen – Logging what button the user clicked or the text of the entry that caused the error might abbreviate the troubleshooting.