Usually, The purposes of log are for troubleshooting and displaying program running status. Good log will help us locate the error easier. Many programmers think log in programs is very simple, but it's not an easy task to write log codes to efficiently locate the error. Here we discuss about program log in three aspects:
- Where to log
- What to log
- Log styles to be avoided
Where to log
1. When calling external functions
When your program is calling some external functions which are not written by you, you need to log before and after the external function call. This will help debug.
1. LOG.debug("Calling external system:" + parameters);
2. Object result = null;
3. try {
4. result = callRemoteSystem(params);
5. LOG.debug("Called successfully. result is " + result);
6. } catch (Exception e) {
7. LOG.warn("Failed at calling xxx system . exception : " + e);
8. }
2. When status changes
Some important status change should be logged, it helps find out the program execution workflow.
1. boolean isRunning;
2.
3. isRunning = true;
4. LOG.info("System is running");
5.
6. //...
7.
8. isRunning = false;
9. LOG.info("System was interrupted by " + Thread.currentThread().getName());
3. The entry and exit of a program
In modular programming, this will ease the error locating process
1. void execute(Object input) {
2. LOG.debug("Invoke parames : " + input);
3. Object result = null;
4.
5. //business logic
6.
7. LOG.debug("Method result : " + result);
8. }
4. Business logical exceptions
Business logic exception should also be logged
1. try {
2. //business logical
3. } catch (IOException e) {
4. LOG.warn("Description xxx" , e);
5. } catch (BusinessException e) {
6. LOG.warn("Let me know anything");
7. } catch (Exception e) {
8. LOG.error("Description xxx", e);
9. }
10.
5. Unexpected execution
Log where some codes may execute.
1. int myValue = xxxx;
2. int absResult = Math.abs(myValue);
3. if (absResult < 0) {
4. LOG.info("Original int " + myValue + "has nagetive abs " + absResult);
5. }
6. Some else conditions
else may eat your request or produce some difficult to understand results
1. Object result = null;
2. if (running) {
3. result = xxx;
4. } else {
5. result = yyy;
6. LOG.debug("System does not running, we change the final result");
7. }
What to log
The program likes a robot when it's running. We can check what it's doing by checking the logs, is it running as expected? So we should record the appropriate logs.
1. The program execution timestamp
1. long startTime = System.currentTime();
2.
3. // business logical
4.
5. LOG.info("execution cost : " + (System.currentTime() - startTime) + "ms");　
2. The progress of data processing
1. LOG.debug("current progress: " + (currentPos * 100 / totalAmount) + "%");
3. Some key variables
1. String getJVMPid() {
2. String pid = "";
3. // Obtains JVM process ID
4. LOG.info("JVM pid is " + pid);
5. return pid;
6. }
7.
8. void invokeRemoteMethod(Object params) {
9. LOG.info("Calling remote method : " + params);
10. //Calling remote server
11. }
Log styles to be avoided
1. Misplaced log
Log should be clear and easy to understand. When checking the log, you should know what the error is:
1. Connection connection = ConnectionFactory.getConnection();
2. if (connection == null) {
3. LOG.warn("System initialized unsuccessfully");
4. }
2. Log into wrong place
1. } catch (ConfigurationException e) {
2. e.printStackTrace();
3. }
3. Wrong level
This happens very frequently when programming. For example, mess up the code error with the user error. If the user login maliciously, there will be many WARNs produced, then the administrator may think the error is from the code. We can respond error to user but don't log the wrong behavior of users.
1. LOG.warn("Failed to login by "+username+");
4. Log loss
Two situations : 1. User wrote few information so that the log has no use;2. User called wrong log method.
1. } catch (Exception ex) {
2. log.error(ex);
3. }
Conclusion
Log is an very important programming practice. Every programmer should have some experience with this. You can share your experience with us.
Author : 冶秀刚 Source : http://www.infoq.com/cn/articles/why-and-how-log
