Logging Best Practices: Defining Error Codes
Editor’s Note: This article is an excerpt from Logging Best Practices: A Practical Guide to Cloud Native Logging (part 1, section 6) published by Manning. This book provides the practical framework you need to transform logging from a reactive debugging tool into a proactive competitive advantage, and it can be downloaded to read in its entirety.
As developers, we tend to write log details with ourselves in mind. This is fine in a DevOps organization where the development team also handles the ops. But many larger organizations may choose to operate an Information Technology Infrastructure Library (ITIL) approach to error and problem management, or you may have a product that people are deploying in locations beyond your reach. But we need to think further ahead. One of the important aspects of ITIL is its definition of a known error:
A Known Error is a problem that has a documented root cause and a Workaround. Known Errors are managed throughout their lifecycle by the Problem Management process. The details of each Known Error are recorded in a Known Error Record stored in a Known Error Database (KEDB). As a rule, Known Errors are identified by Problem Management, but Known Errors may also be suggested by other Service Management disciplines, e.g., Incident Management. (Source: IT Process Maps wiki)
In simple terms, an organization will keep a record of errors with resolutions. This is why we assign errors with error codes. An error code allows us to provide a simple lookup for an error that can be linked to the appropriate documentation. The documentation should describe the error and provide details, including a remedial set of actions to perform (this is essential if this involves bringing the system back to an optimal state without corrupting or losing data).
If, of course, the log event is recorded and acted upon before things really go wrong, then the actions could be preventative in nature.
The cause of the error could be either from a user action or a bug in the application that has been caught; either way, we should add error codes to the log information. It is best not to pop up error codes in a user interface (UI), as you’re likely to undermine user confidence in your product. But that shouldn’t stop you from linking error codes to messages suitable for users when a user action triggers a problem.
What Are Error Codes Used For?
Error codes make it straightforward to enable customers to look up errors, descriptions and recommended responses to incorporate into a known error database (KEDB). Building such error code content may seem very demanding; this can be far from the case.
While developing software, the simplest solution is to have a collaborative spreadsheet that allocates error IDs, ensuring the IDs are unique. Then capture the expected cause with a brief description from the developer. Building out resolution documentation can always be done later.
Benefits of Using Error Codes
One of the benefits of using error codes is that it becomes pretty easy to standardize and internationalize the documentation about the errors. The error codes are language- and locale-agnostic; once you have the code, you can then look up the code documentation in an appropriate language.
There are all sorts of additional tricks that you can incorporate into the software development processes, such as including the documentation in the code management tool. Hence, you release the document with the code so that the details are linked to your release process. Code-quality tooling could look for errors or fatal log entries and apply a regular expression to see if an error code is linked to it, and so on.
Error Code Numbering
Here are a few tips for creating your error code numbering:
- Don’t use leading zeros in the number unless it’s prefixed with an alpha character — this risks getting truncated if handled numerically, or creates additional work for formatting (e.g., number string with stipulated length and prefix character). Then, if that number is converted back to a string, it won’t match as a key for information lookup anymore.
- Don’t start at 1; it’s best to start with the lowest digit for the full range (e.g., 1000).
- Make the error code easy to find using search tools (e.g., 1000 as a code is less likely to be indexed than something like AppErr1000). For example, Oracle prefixes its database error codes with ORA and WebLogic error codes start with BEA; thus, they’re more likely to be indexed and more unique in searches.
- It is tempting to simply document all the error codes within a piece of code (e.g., class, interface, header file, depending on your language); after all, there is one place to go, and documentation can be generated from the code. But this is not recommended. You will end up with code on which everything will become dependent and constantly changing while the system is being developed. Each addition to the error code makes a code change with an enormous dependency impact. Code changes with that much impact will give rise to concerns (even if they’re not justified) and resistance to the change.
- It’s better to compile the details in a shared knowledge repository, such as a wiki or collaborative knowledge base, that everyone can maintain without consequence. Note that defining a local subset of errors in the code is fine — this applies the DRY (“don’t repeat yourself”) principle. For example, error codes relating to a specific module could be defined together, as adding an error code is likely to go hand in hand with the module development.
- Group error codes together into families, as seen in the HTTP RFC, but be pragmatic about it; an error code may logically belong in two groupings (e.g., is a DB connection error a database issue or a network connectivity issue?).
- This doesn’t necessarily mean reserving ranges of numbers. Still, the codes could be prefixed or postfixed with a shortcode to provide a scope at the product or subsystem level; for example, BEA-00000 and ORA-00000 denote error codes for two different Oracle products (WebLogic and Oracle Database).
- If you use the same error code from different exceptions, try to differentiate the point of origin in the supporting information.
- Consider the error code consumer; an error may come from a single location but have different causes, so use different error codes for the causes. This will make the support team’s job or remediation easier.
Using Standard Errors
Some technologies provide codes to indicate success and errors that have been well documented, such as those for HTTP (RFC); others include SMTP (email services) and Oracle WebLogic Server.
Using such codes in logs helps provide more context through a common meaning and understanding — as long as they are used correctly. For example, the temptation to simply do everything through the standard HTTP 200 or 400 codes doesn’t help. Using an HTTP 413 code to tell the requester they sent too much data is far more effective and meaningful, not to mention that this will show up in the logs for any network routing devices.
The use of predefined error codes does need to be judged with care, as exception classes in software can be considered a special form of error code. But these circumstances could also reduce clarity.
Codes Can Be for More Than Errors
Error codes are the most important messages to be uniquely identifiable. The principle of associating codes to documentation for operational (rather than user) processes means that you can hook the event back to specific operational recommendations that could range from performing database optimization processes to archiving log files.
You’ve just read an excerpt from the Manning book “Logging Best Practices” — you can download a complimentary copy of the entire book.
