调试与日志机制

Nginx 提供多级日志系统，模块可通过标准日志接口输出调试信息，配合 gdb 实现高效问题定位。

日志级别

标准日志级别

级别	常量	说明
0	NGX_LOG_STDERR	直接输出到 stderr
1	NGX_LOG_EMERG	紧急，系统无法使用
2	NGX_LOG_ALERT	警报，需立即处理
3	NGX_LOG_CRIT	严重错误
4	NGX_LOG_ERR	错误
5	NGX_LOG_WARN	警告
6	NGX_LOG_NOTICE	通知
7	NGX_LOG_INFO	信息
8	NGX_LOG_DEBUG	调试（需编译时启用 --with-debug）

日志输出

标准日志输出

// 基本日志
ngx_log_error(NGX_LOG_ERR, r->connection->log, 0,
              "my_module: request failed, uri: %V", &r->uri);

// 调试日志（需 --with-debug）
ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
               "my_module: status=%i, bytes=%O", status, bytes);

// 带连接信息的日志
ngx_log_error(NGX_LOG_WARN, c->log, 0,
              "my_module: connection from %V", &c->addr_text);

调试日志需编译时启用 --with-debug，并在配置中设置 error_log logs/error.log debug;

日志格式控制符

控制符	类型	说明
`%V`	ngx_str_t *	字符串
`%s`	char *	C 字符串
`%d`	int	整数
`%i`	ngx_int_t	Nginx 整数
`%O`	off_t	偏移量
`%T`	ngx_time_t *	时间
`%M`	size_t	内存大小
`%P`	ngx_pid_t	进程 ID

错误日志配置

配置文件

nginx

# 全局错误日志
error_log /var/log/nginx/error.log warn;

# HTTP 级别
http {
    error_log /var/log/nginx/http_error.log info;
}

# Server 级别
server {
    error_log /var/log/nginx/server_error.log debug;
}

日志级别可逐层覆盖，子块可设置更详细或更粗略的日志级别。

调试技巧

gdb 调试

Bash

# 启动调试
gdb /usr/sbin/nginx

# 设置断点
break ngx_http_my_handler
break ngx_event_process_posted

# 运行
run -g "daemon off;"

# 查看变量
print r->uri
print *c->read

# 线程切换
info threads
thread 2

核心转储

Bash

# 启用核心转储
ulimit -c unlimited

# Nginx 配置
worker_rlimit_core 512m;
working_directory /tmp/nginx_cores;

# 分析核心转储
gdb /usr/sbin/nginx /tmp/nginx_cores/core
bt  # 查看调用栈

内存泄漏检测

// 启用内存池调试
#define NGX_DEBUG_PALLOC  1

// 编译时启用
./configure --with-debug --with-debug-memory

// 运行时查看内存池使用情况
ngx_log_debug1(NGX_LOG_DEBUG_ALLOC, cycle->log, 0,
               "pool: used=%uz, size=%uz",
               pool->d->last - pool->d->start,
               pool->d->end - pool->d->start);

Valgrind 检测

Bash

# 内存泄漏检测
valgrind --leak-check=full --show-leak-kinds=all \
         --track-origins=yes \
         /usr/sbin/nginx -g "daemon off;"

# 常见错误类型
# Invalid read/write: 越界访问
# Conditional jump on uninitialised value: 未初始化变量
# Definitely lost: 内存泄漏

要点总结

Nginx 日志分 9 级，DEBUG 级别需 --with-debug 编译
日志通过 ngx_log_error 和 ngx_log_debugN 输出，支持多种格式控制符
错误日志可全局/HTTP/Server/Location 逐层配置
gdb 调试通过 run -g "daemon off;" 前台运行，配合断点定位问题
Valgrind 用于内存泄漏和非法访问检测，是 C 模块调试利器

📝 发现内容有误？点击此处直接编辑