For programs, a good logging style can greatly reduce the cost of troubleshooting and enhance the robustness and operationality of the program. However, most development students did not raise the importance of logs as high as the code itself. This article discusses some of my personal best practices for logging.
Basic Principles
Use logs as the second UI of the program
The first UI of the software is of course the user or API caller, and the log is used as the second UI for development, operation and maintenance, and partners to detect and troubleshoot online application status. The quality of the log is part of the quality of the code.
When writing logs, people who are considering reading logs cannot access the code
Generally speaking, the role of looking at logs is not just the person who develops code, but also the person who is online on duty, after-sales personnel, and other partner systems may all rely on logs to troubleshoot problems. Today's IT system logs are easier to collect and centralize, making it easier for different roles to access logs. For APIs, especially complex APIs involving multiple other subsystem calls, good logs can provide rich problem-solving basis for callers and online duty. When printing logs in code, you should consider the roles that cannot access the code.
The main user of the log is Human, and the secondary user is the machine, so readability is very important
Readability contains a lot of content. The following will explain some principles, but the most basic principle is that indentation, spaces, etc. need to make it easier for readers to read. At the same time, the log format also ensures easy pattern parsing (simple string matching, not complex regularity)
What is the purpose of considering logs
The purpose of logs is not only online debugging, but also recording performance or collecting data analysis. Considering the purpose of logs in the system, it is targeted when writing logs.
Best Practices
Add context to the log
Very General logs are very bad, not only do not help locating problems, but also easily cause confusion. For example, the following log:
2021-11-30 16:44:52,725 [WARN] Connection failed!It is impossible to locate which piece of code is, what failed to connect, and don’t know what failed parameters are. The better log format is as follows:
Similar questions include:
//don't do that
//do that
IndexOutOfBoundsException: index 25 is greater than list size 20.For logs, try to avoid logs that are too general, remember our principles, and know who our second UI is the target audience, and most people who view logs may not be able to access the code.
End-to-end log & concurrent thread logging issues
Each request needs to have a unique identifier corresponding to it, usually a GUID, which is mainly used for two purposes
1. Uniquely identify a request between different systems or microservices
2. Different concurrent threads in the same application uniquely identify a request
For example, we can track a complete request process through the following GUID
careyson@CareySonMac log % grep "C97E2488-170A-4D01-8B90-BE562FD78342"
2021-11-30 16:44:52,725 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] XXX Start
2021-11-30 16:44:53,009 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Begin Instance Rule Check [source version=, target version=]
2021-11-30 16:44:53,010 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] rule check passed. [source version=, target version=]
2021-11-30 16:44:53,011 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Starting check config
2021-11-30 16:44:53,078 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Check config Complete
2021-11-30 16:44:53,079 [WARN] ModifyDBInstanceVersionImpl(46) - [C97E2488-170A-4D01-8B90-BE562FD78342,yunji-dbsingle2,ModifyDBInstanceVersion] Starting get Source Custins info
.....The variable value is separated from the constant value
Separating variable values from constant values can make logs easier to read, and searching for both the code and the log itself will also become simple. If you use tools to extract parameter values, the following is an example:
If the URL is a very long string, the reading experience will be very bad.
Differentiate between Warn and Error
Logs are also classified according to their severity, and the most commonly used industry standards are Info, Warn and Error. Info usually has nothing to say. The program works normally in line with expectations. Recording relevant information during the process is that Info, Warn and Error are worth mentioning.
Warn means the program works properly, but there are some problems that are usually within our expectations.
Error means that the program exception is not within our expectations.
Here is a simple example of calling other services in a program:
If possible, attach a KB or an error code when an error occurs.
People who write programs usually have a certain understanding of the business represented by the program, but other log users may not have background knowledge or business restrictions. It is usually difficult to explain clearly in limited logs. If there are corresponding KBs or help documents and error codes, they can be attached to the log to help log users quickly understand the background. For example, the following example:
Avoid recording of sensitive information
Logs do not have a high security level like databases, that is, the security permissions to access logs are usually far lower than those of other applications. Today's logs are more centralized after uploading, and they cannot control the spread of the logs. Therefore, please do not record sensitive information, including password information, Security Token information, sensitive identity information, etc.
Logging in English
English records are not just a matter of standardization and easy to read, but today's IT systems, logs may be centralized by multiple systems. As long as one of these systems does not support UTF format, it may lead to garbled code. Using English can try to avoid these troubles.
summary
For programs, the code quality includes logs in addition to the code itself. Taking logs seriously as the second UI of the program can not only greatly reduce the cost of our program debugging and development, but also make the operation and maintenance errors of the program more concise and bugs can be discovered earlier.