How to Write Error Logs That Facilitate Troubleshooting

How to Write Error Logs That Facilitate Troubleshooting

Writing error logs aims to provide important clues for diagnosing and solving problems, but in practice log content often varies, lacks context, or is ambiguous, making troubleshooting difficult.

How Errors Are Generated

Errors in a system can originate from three main sources:

Invalid parameters from upper‑level systems.

Errors caused by interaction with lower‑level systems, which include: Successful processing in the lower system but communication failure, leading to data inconsistency. Successful communication but failure in the lower system’s processing.

Errors generated within the current layer itself.

Each cause is described with typical scenarios and improvement measures, such as parameter validation, timeout compensation, static analysis, comprehensive exception handling, reducing coupling, separating algorithms, ordering parameters correctly, checking for null pointers, logging INFO at subsystem boundaries, handling transactions and concurrency, verifying configurations, documenting business logic, reviewing design, using mature libraries, updating outdated code, monitoring hardware resources, etc.

Common Error Types

Entity record not found.

Incorrect entity configuration.

Insufficient resources.

Pre‑condition not satisfied.

Post‑condition check failed.

Performance‑induced timeout.

Cross‑subsystem communication errors.

Guidelines for Writing More Troubleshootable Error Logs

Be as complete as possible: describe the scenario, the error, possible causes, and suggested solutions.

Be specific: indicate which resource, entity, or parameter caused the problem.

Be direct: the log should allow a reader to understand the root cause at a glance.

Integrate existing experience into the system so new developers receive helpful hints.

Keep formatting tidy and consistent.

Include unique request identifiers (time, entity ID, operation name) to aid correlation.

Typical troubleshooting steps: log in to the application server → open the log file → locate the error entry → follow the clues to diagnose and fix the issue.

For example, a business use case A.B.C may succeed in A and B but fail in C; B must roll back based on C’s error code, and A must roll back based on B’s response.

Code examples illustrate how to improve log messages using String.format , adding interface names, parameters, and context:

if ((storageType == StorageType.dfs1 || storageType == StorageType.dfs2) && (zone.hasStorageType(StorageType.io3) || zone.hasStorageType(StorageType.io4))) {
    // ...
} else {
    log.info("zone storage type not support, zone: " + zone.getZoneId() + ", storageType: " + storageType.name());
    throw new BizException(DeviceErrorCode.ZONE_STORAGE_TYPE_NOT_SUPPORT);
}

Other refactored examples show how to include failing IP addresses, subnet details, VM IDs, and resource shortages directly in the log message.

Finally, a recommended log format is:

log.error("[Interface] Some error happens. Params: %s. Probably because ... . Probably need to ... .");

Answering common questions: using String.format has negligible performance impact for error logs; a standardized template saves time when development is rushed; and info , warn , error should be used for normal operation, minor issues, and serious failures respectively.