In the last posts I presented general guidelines to improve your logging practices. Today we’ll discuss further about how and what you log. We will focus in some techniques to help you write clear and descriptive log messages.
Before we start, let me remind you of the related items I presented in the first post:
Be clear: write short statements that go straight to the point. Avoid directly referencing symbols of your code.
Along with:
Check the spelling and grammar of your log messages.
And:
Use the correct message level
Achieving this goal can be quite complicated, though. There are many details to watch out for. Some of decisions that a developer usually has to make are:
- Deciding the relevance of the event
- Deciding what should be logged
- Complying with legal regulations
- Complying with company standards, etc.
In addition to the aforementioned details, a few other factors add complexity to the process. Given how spread software development is nowadays, it’s not uncommon to have different components developed in different parts of the world. As such how fluent you are on the language – not the programming one – used to log the messages makes the process more or less complex. Additionally, your understanding and knowledge about the industry terms are paramount to properly describe the events being logged.
To improve the quality of the log messages you can follow these guidelines:
- Know you audience: you should identify the individuals that will read your messages and their ability to understand technical and industry terms.
- Properly identify the relevance of the event: ask yourself “what are the consequences of the event being logged?”and use that as guideline to support your decision. When in doubt, try this:
- Does the event prevent the application to continue execution? If yes, then it’s a critical or fatal error.
- Does the event prevent the transaction to continue but allow the application to continue execution? If yes, then it’s an error, a handled exception or any similar critical level that represents so.
- Does the event indicate that the application or transaction may failure as a result of the event? Does the event indicate that the consistency of the data used by the application is at risk due to the outcome of the event? If yes to any of these questions, then it is a warning event.
- Is the event expected or does it indicate a change in the transaction flow, stored data or communication exchange in such a way that the outcome can’t be identified yet and is likely to be successful? If yes, then it’s an informational message.
- Is the event bound and/or related to changes in the stored data or communication exchanges that could possibly result in legal actions against your company or your client? If yes, then it’s an informational message.
- Does the event support problem investigation and/or overcome a limitation in our programming/debugging environment? If yes, then it’s a debug message.
- Does the event support problem investigation and/or overcome a limitation in our programming/debugging environment by tracing the steps that your transaction or application is passing through? If yes, then it’s a trace message.
- Write log messages that allow the reader the reason about the event and the outcome of the event in place.
- Write log messages that you can easily copy and paste to an email or instant message and do not require you to explain them. That saves your time.
- As explained on the previous post, avoid fancy messages. They reduce the readability of the messages.
- Don’t Pretend You Are Writing A Title.
- Prefer to document the event and describe the outcome: “The user ‘orpiske.net’ has successfully logged in”.
Although there will be cases in which you will have to ignore these guidelines, you can ease the management and support of your application by following them. These guidelines will also to help prevent the events your application pass through to be misinterpreted. For all the other cases not covered by them, you can stick to the good sense, simplicity and your application needs.
