How to Write Error Logs That Are Easier to Troubleshoot

Effective error logs are essential for quickly locating and solving problems in software systems, but many logs lack sufficient detail, context, or clarity, making troubleshooting time‑consuming.

The article categorizes error sources into three layers: illegal parameters from upper‑level systems, interaction errors with lower‑level systems (including communication failures, mismatched responses, and error codes), and mistakes within the current layer itself.

Common causes within the current layer include negligence (e.g., typo mistakes, boundary errors), insufficient exception handling, tight logical coupling, incorrect algorithms, swapped parameter order, null‑pointer exceptions, network communication failures, transaction/concurrency issues, configuration errors, unfamiliarity with business logic, design flaws, unknown edge‑case bugs, outdated code, and hardware problems.

For each cause, concrete improvement measures are suggested, such as using static analysis tools, comprehensive unit tests, thorough input validation, short and stateless functions, clear interface contracts, separating algorithms for independent testing, type‑specific parameters, null checks, INFO logs at subsystem boundaries, and robust monitoring of CPU/memory/network metrics.

When writing error logs, the article recommends six principles: completeness (describe scenario, cause, and solution), specificity (include exact resource or parameter details), directness (immediate understanding of the issue), integration of known solutions, clean formatting, and inclusion of unique identifiers (time, entity ID, operation name).

Typical troubleshooting steps are outlined: log into the server, open the log file, locate the error entry using timestamps or keywords, and follow the guidance provided by the log to diagnose and fix the problem.

Several code examples illustrate poor logging practices and their improved versions. For instance, replace vague messages like log.error("control ip insert failed", ex) with detailed ones such as log.error(String.format("[addControlIp] failed to insert control IP %s", ip), ex) . Use String.format or parameterized logging to embed context, and ensure messages are natural‑language sentences.

The article also provides a template for standardized error messages: log.error("[Interface] [Error Message] happens. [Params] [Probable Reason]. [Suggested Action].") .

Finally, it answers common questions about the performance impact of String.format in logging and how to balance time constraints with log quality, emphasizing that a consistent format can streamline the process.