How to Write Effective Error Logs for Faster Debugging

In programming, error logs are essential for diagnosing and solving problems, but often their content and format are inconsistent, incomplete, or unclear, which hampers efficient troubleshooting.

How Errors Are Created

Errors can originate from three sources: (1) illegal parameters passed from upper‑level systems; (2) errors during interaction with lower‑level systems, which include communication failures or processing failures; and (3) errors generated within the current layer itself.

Common Causes and Improvements

Negligence : simple mistakes such as using & instead of && or = instead of ==. Use static analysis tools and comprehensive unit tests to catch them.

Insufficient Exception Handling : e.g., not validating input ranges. Validate inputs, use regular expressions, and provide detailed, user‑friendly messages.

Tight Logical Coupling : complex inter‑module dependencies make local changes affect the whole system. Write short, stateless functions, keep modules orthogonal, and continuously refactor.

Incorrect Algorithms : separate algorithms from business logic and verify them with unit tests, especially for reversible operations.

Parameter Order Mistakes : ensure parameter types are specific and test interfaces for correct ordering.

Null‑Pointer Exceptions : check object initialization and nullity before use.

Network Communication Errors : add INFO logs at the end of one subsystem and the start of the next to capture timing clues.

Transaction and Concurrency Issues : log INFO for shared‑state modifications.

Configuration Errors : log configuration loading results and verify all items at startup.

Business Knowledge Gaps : document business use‑cases, pre‑conditions, and post‑checks; keep them updated when requirements change.

Design Problems : write and review design documents that describe background, requirements, performance goals, and potential trade‑offs.

Unknown Details (e.g., buffer overflow, SQL injection) : choose mature, well‑tested libraries and annotate data models to ignore unknown fields.

Time‑Dependent Bugs : monitor library updates and security patches.

Hardware‑Related Errors : monitor CPU, memory, and storage metrics.

Typical Error Scenarios

Entity not found in database – specify which entity.

Incorrect entity configuration – indicate the problematic setting.

Insufficient resources – detail the missing resource and required amount.

Pre‑condition not met – describe the required condition.

Post‑validation failure – explain the expected state.

Performance‑induced timeouts – identify the bottleneck.

Cross‑system state inconsistencies – provide enough context to locate the error.

Guidelines for Writing Better Error Logs

Be as complete as possible: include the scenario, possible cause, and suggested solution.

Be specific: mention the exact resource or parameter that failed.

Be direct: the log should immediately convey the reason and remedy.

Integrate past experience: reuse known solutions in the log message.

Maintain a clean, consistent format.

Include key identifiers such as timestamp, entity ID, and operation name.

Typical troubleshooting steps: log into the server, open the log file, locate the error entry, and follow the clues to diagnose and resolve the issue.

Example before/after:

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

Improved log format:

log.error("[modify disk attribute] None of [diskWbps,diskRbps,diskWiops,diskRiops] is specified for disk id: " + diskId);

General log template:

log.error("[InterfaceOrOperation] [ErrorMessage] happens. [Parameters] [ProbableCause]. [SuggestedAction].");

By following these practices, error logs become a valuable documentation source that aids both immediate debugging and long‑term system maintenance.