Mastering Log Practices: From Levels to Formats for Reliable Backend Systems

Purpose and Requirements of Logging

Logs provide audit trails, help locate root causes, trace execution, monitor data changes, collect performance metrics, and capture environment information. In production, logs are the first source of information for diagnosing failures.

Readability: Use clear English messages, avoid decorative symbols, and separate logs into logical files.

Performance: Logging incurs I/O; avoid logging inside large loops and guard expensive string construction with level checks such as isDebugEnabled().

Disk usage: Implement log rotation and periodic cleanup to prevent disks from filling.

Retention: Keep logs for a reasonable period to enable retrospective analysis.

Log levels: In production, filter at INFO or higher while ensuring sufficient diagnostic detail.

#define DRV_LOG_FATAL(fmt, ...)   hlog_format(HLOG_LEVEL_FATAL, "PluginDriver", "[%s(%d)] " fmt, __FUNCTION__, __LINE__, ##__VA_ARGS__)
#define DRV_LOG_ERROR(fmt, ...)   hlog_format(HLOG_LEVEL_ERROR, "PluginDriver", "[%s(%d)] " fmt, __FUNCTION__, __LINE__, ##__VA_ARGS__)
#define DRV_LOG_WARN(fmt, ...)    hlog_format(HLOG_LEVEL_WARN,  "PluginDriver", "[%s(%d)] " fmt, __FUNCTION__, __LINE__, ##__VA_ARGS__)
#define DRV_LOG_INFO(fmt, ...)    hlog_format(HLOG_LEVEL_INFO,  "PluginDriver", "[%s(%d)] " fmt, __FUNCTION__, __LINE__, ##__VA_ARGS__)
#define DRV_LOG_DEBUG(fmt, ...)   hlog_format(HLOG_LEVEL_DEBUG, "PluginDriver", "[%s(%d)] " fmt, __FUNCTION__, __LINE__, ##__VA_ARGS__)
#define DRV_LOG_TRACE(fmt, ...)   hlog_format(HLOG_LEVEL_TRACE, "PluginDriver", "[%s(%d)] " fmt, __FUNCTION__, __LINE__, ##__VA_ARGS__)

Log4j Overview

Log4j is an Apache logging framework that separates log generation from output configuration. It supports multiple destinations (console, file, socket, GUI) and flexible message formatting via three core components:

Logger: Controls which statements are enabled and applies level filtering.

Appender: Determines the output target (e.g., console, file).

Layout: Formats each log entry (timestamp, level, location, message, error code, etc.).

Log4j Levels

TRACE: Very fine‑grained events, typically function entry/exit without variable data.

DEBUG: Detailed information useful during development.

INFO: High‑level operational messages that describe normal flow.

WARN: Potential issues that do not stop execution.

ERROR: Errors that allow the program to continue but indicate a problem.

FATAL: Severe errors that cause the application to abort.

The hierarchy is

ALL < TRACE < DEBUG < INFO < WARN < ERROR < FATAL < OFF

. In practice, most projects use the subset DEBUG < INFO < WARN < ERROR.

Logging Style Examples (using DRV_LOG_* macros)

TRACE

DRV_LOG_TRACE("Connect Execute start");
DRV_LOG_TRACE("Connect Execute finish");
DRV_LOG_TRACE("DisConnect func");
DRV_LOG_TRACE("Execute DisConnect function succeed.");

INFO

DRV_LOG_INFO("- UpdataEvent nchan= %d, EventID = %d.", iChannelNo, nEventType);
DRV_LOG_INFO("- do not support doControl");
DRV_LOG_INFO("- channelId = %s, nStatusType = %d", channelId.c_str(), nStatusType);

DEBUG

DRV_LOG_DEBUG("- Output alarm: grid=%d, count=%d, content=%s.", datas.data1.chn, datas.data1.alarm_num, datas.data1.alarms);
DRV_LOG_DEBUG("- datas.data1.huab = %d", datas.data1.huab);

WARN

DRV_LOG_WARN("[0x%08x] - invalid event msg, discard it", DRV_INVALID_ARG);
DRV_LOG_WARN("[0x%08x] - Can't find channel by channelId");

ERROR

DRV_LOG_ERROR("Init DwSDK failed; errCode=%d", initRet);
DRV_LOG_ERROR("Connect device failed");
DRV_LOG_ERROR("[0x%08x] - DWSdk.errorcode=0x%08x] Init DwSDK failed", DRV_INIT_FAILED, initRet);

Formatting tip: the pattern 0x%08x prints an integer as an eight‑digit hexadecimal number prefixed with 0x (e.g., printf("0x%08x", 0x1234) outputs 0x00001234).

Guidelines for Effective Logging

Write logs with business‑relevant descriptions to indicate which processing step is being executed.

Avoid logging sensitive data such as usernames or passwords.

Prefer English messages to prevent encoding issues.

Include standard fields in each entry: timestamp, log level, source file and line, thread or request identifier, message, and optional error code.

Use log rotation (e.g., size‑based or time‑based) and automated cleanup to manage disk usage.

Guard expensive log statements with level checks to minimize performance impact.