Nginx日志深度挖掘：专为开发者定制的Debug日志教程

烟雨平生

发布于 2024-05-27 16:29:01

1770

发布于 2024-05-27 16:29:01

文章被收录于专栏：数字化之路

接上回：Nginx有debug日志吗？
安装支持debug的Nginx
打开Nginx的debug配置
实战小技巧：debug_connection
小结
进阶：debug log+热升级
彩蛋:百万并发下Nginx的优化之道

在开发和调试Nginx配置或模块时，打印Nginx处理请求过程中的日志对于定位问题至关重要。

本文将引导读者了解如何从源代码重新编译Nginx以包含debug支持，并展示如何定制Nginx以输出debug级别的日志信息。

此外，我们还将讨论如何仅针对特定IP地址记录debug日志，从而优化日志管理，确保只有关键请求的调试信息被记录。通过本文的指导，你将能够有效地使用Nginx的debug日志来观测和调试你的服务器行为。

安装支持debug的Nginx

按上一篇留的小问题：你的nginx error.log日志中示例中的debug日志吗？答案是：没有的。唐成，公众号：的数字化之路Nginx代理：掌握proxy_pass的正确姿势

默认情况下，Nginx是不支持debug调试功能的。因此需要自己从源代码安装一个支持debug的Nginx。 Nginx主要有以下三种版本：

Mainline version 开发版
Stable version 稳定版
Legacy version 历史版本

https://nginx.org/en/download.html

本次使用Stable version。

准备编译环境。为了从源代码编译Nginx，系统需要具备某些必要的条件。除了编译器之外，如果想启用SSL支持和能够使用rewrite模块，那么还需要提供相应的OpenSSL和PCRE（Perl Compatible Regular Expressions）及开发头文件。本次不涉及这些，就不展开讲了。不过，分享一个小技巧：Linux下,基于rpm 使用

sudo yum install nginx

，或基于deb 使用

sudo apt-get install nginx

，mac可以使用

brew install nginx

来把Nginx安装到操作系统的标准位置下，同时，nginx相关的依赖也会安装。

% brew install nginx
==> Downloading https://formulae.brew.sh/api/formula.jws.json
######################################################################### 100.0%
==> Downloading https://formulae.brew.sh/api/formula_tap_migrations.jws.json
######################################################################### 100.0%
==> Downloading https://formulae.brew.sh/api/cask.jws.json
######################################################################### 100.0%
nginx 1.25.3 is already installed but outdated (so it will be upgraded).
==> Fetching dependencies for nginx: ca-certificates, openssl@3 and pcre2
==> Fetching ca-certificates
==> Downloading https://mirrors.cloud.tencent.com/homebrew-bottles/ca-certificat
######################################################################### 100.0%
==> Fetching openssl@3
==> Downloading https://mirrors.cloud.tencent.com/homebrew-bottles/openssl%403-3
######################################################################### 100.0%
==> Fetching pcre2
==> Downloading https://mirrors.cloud.tencent.com/homebrew-bottles/pcre2-10.43.m
######################################################################### 100.0%
==> Fetching nginx

此时Nginx的常用依赖已经安装好了，我们就继续。

源码的安装一般由3个步骤组成: 配置(configure)、编译(make)、安装(make install)。本次示例的操作系统：

STEP1：先下载源文件并解压到指定目录。从https://nginx.org/en/download.html地址下载Nginx。本次从上面的页面下载nginx-1.26.0.tar.gz。

 %mkdir opt
 %cd opt
 %cp /Users/root/Downloads/nginx-1.26.0.tar.gz .
 %tar -xzf nginx-1.26.0.tar.gz
 %mkdir debug_nginx 
 %cd nginx-1.26.0

从源代码编译。要打开Nginx的debug日志打印，现在就进入关键阶段了。 Nginx源代码的编译需要使用configuree脚本来生成Makefile文件。

configure脚本支持的常用选项：

--with-debug 这个选项用于启用Nginx的调试日志。在生产环境的系统中不推荐使用该选项
--prefix=<path> 指定Nginx安装的根目录，所有其它的路径都要依赖于此选项。如果未指定，默认为/usr/local/nginx/目录
--conf-path=<path> 如果在命令行没有指定配置文件，那么将会通过这里指定的路径，Nginx将会去那里查找它的配置文件。如果未指定，默认为<prefix>/conf/目录
--pid-path=<path> 指定的文件将会写入Nginx master进程的pid，通常在/var/run下
--sbin-path=<path> 指定Nginx可执行文件安装路径。此项只能在安装时指定，如果未指定，默认为<prefix>/sbin/nginx/目录
--error-log-path=<path> 在nginx.conf中未指定error_log指令的情况下，指定默认的错误日志的路径。如果未指定，默认为<prefix>

这些选项对于Nginx都是有效的，模块可以被独立激活。现在我们来使用configure脚本的配置选项来设计出自己的Nginx二进制。本次，我们只打开调试日志和指定Nginx的安装根目录。

STEP2：生成Makefile文件

%./configure --with-debug --prefix=/Users/root/opt/nginx/debug_nginx

configure脚本执行后，输出摘要：

checking for PCRE2 library ... found
checking for zlib library ... found
creating objs/Makefile

Configuration summary
+ using system PCRE2 library
+ OpenSSL library is not used
+ using system zlib library

nginx path prefix: "/Users/root/opt/nginx/debug_nginx"
nginx binary file: "/Users/root/opt/nginx/debug_nginx/sbin/nginx"
nginx modules path: "/Users/root/opt/nginx/debug_nginx/modules"
nginx configuration prefix: "/Users/root/opt/nginx/debug_nginx/conf"
nginx configuration file: "/Users/root/opt/nginx/debug_nginx/conf/nginx.conf"
nginx pid file: "/Users/root/opt/nginx/debug_nginx/logs/nginx.pid"
nginx error log file: "/Users/root/opt/nginx/debug_nginx/logs/error.log"
nginx http access log file: "/Users/root/opt/nginx/debug_nginx/logs/access.log"
nginx http client request body temporary files: "client_body_temp"
nginx http proxy temporary files: "proxy_temp"
nginx http fastcgi temporary files: "fastcgi_temp"
nginx http uwsgi temporary files: "uwsgi_temp"
nginx http scgi temporary files: "scgi_temp

‍‍如上所示，configure脚本按照--prefix参数设置了根目录。

STEP3：编译并安装Nginx软件

%make && sudo make install

命令执行后，输出摘要：

    || cp conf/scgi_params '/Users/root/opt/nginx/debug_nginx/conf'
cp conf/scgi_params \
    '/Users/root/opt/nginx/debug_nginx/conf/scgi_params.default'
test -f '/Users/root/opt/nginx/debug_nginx/conf/nginx.conf' \
    || cp conf/nginx.conf '/Users/root/opt/nginx/debug_nginx/conf/nginx.conf'
cp conf/nginx.conf '/Users/root/opt/nginx/debug_nginx/conf/nginx.conf.default'
test -d '/Users/root/opt/nginx/debug_nginx/logs' \
    || mkdir -p '/Users/root/opt/nginx/debug_nginx/logs'
test -d '/Users/root/opt/nginx/debug_nginx/logs' \
    || mkdir -p '/Users/root/opt/nginx/debug_nginx/logs'
test -d '/Users/root/opt/nginx/debug_nginx/html' \
    || cp -R html '/Users/root/opt/nginx/debug_nginx'
test -d '/Users/root/opt/nginx/debug_nginx/logs' \
    || mkdir -p '/Users/root/opt/nginx/debug_nginx/logs'

通过以上步骤，我们已经成功编译并安装了带有debug功能的Nginx。

高频使用的options:

-t test configuration and exit。用于检查Nginx服务器配置文件是否有语法错误，可以与“-c”联用，使输出内容更详细，这对查找配置文件中的语法错误很有帮助。 eg: nginx -t -c <path-to-nginx.conf>
-s signal send signal to a master process: stop, quit, reopen, reload

启动安装好的Nginx软件:

% ./sbin/nginx

打开Nginx的debug配置

在Nginx中这个功能需要借助error_log指令来实现。

error_log file|stderr[debug|info|notice|warn|error|crit|alert|emerg];

从语法结构可以看到，Nginx服务器的日志支持输出到某一固定的文件file或输出到标准错误输出stderr；日志的级别是可选项，由低到高分为debug(需要在编译时使用--with-debug开启debug开关)、info、notice、warn、error、crit、altert、emerg等。需要注意的是，设置某一级别后，比这一级别高的日志也会被记录。比如设置warn级别后，级别为warn以及error、crit、altert和emerg的日志都会被记录下来。

默认情况下，Nginx的debug日志会输出到标准错误(stderr)。

为了将debug日志输出到文件，我们需要修改Nginx配置文件，添加以下内容：

error_log  logs/error.log  debug;

然后，重启Nginx以应用更改。

 %cd debug_nginx
 %./nginx -s reload

以本次为例，带有debug级别日志文件，可以在/Users/root/opt/nginx/debug_nginx/logs/error.log找到。

来看看debug日志中都有哪些内容：

重新打开一个Shell窗口，执行命令

debug_nginx % tail -f logs/error.log

show the debug log:

 debug_nginx % vi conf/nginx.conf

配置2： location / { proxy_pass http://www.ai-as.net/; } 唐成，公众号：的数字化之路Nginx代理：掌握proxy_pass的正确姿势

debug_nginx % ./sbin/nginx -s reload 
debug_nginx % curl 127.0.0.1

Nginx的处理请求的过程一目了然，信息很丰富。

但有一个问题：Nginx同时处理多个请求时，都会打印debug日志，这些日志多且混在一起，往往会不知从何看起！这种无法在uat或pro使用的“玩具”功能，看着很鸡肋呀

能不能增加限制条件，只有满足条件的请求才会打印debug日志？

答案是：有。

实战小技巧：debug_connection

debug日志级别一旦打开后，日志量是特别巨大的，很多同学都不知从何看起。

我们做的每一件事就是减少debug日志的打印，这需要借助debug_connection指令来控制debug级别在error.log日志中的输出。

debug_connection address|CIDR|unix;

功能：针对特定客户端打印DEBUG级别的日志，其它日志仍然遵从error_log指令后设置的日志级别。这个指令仍然需要Nginx在生成Makefile时configure脚本中必须加编译选项：

--with-debug

默认情况下，debug_connection是没有配置的。且设置error_log指定的日志级别为非debug。

本次就把error_log都注掉：

#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

增加debug_connection配置：

events {
    worker_connections  1024;
    debug_connection 127.0.0.1;
}

% ./sbin/nginx -s reload
% curl 127.0.0.1

可以看到logs/error.log中仍然输出了debug日志。

附本次示例中使用nginx.conf：

#user  nobody;
worker_processes  1;

#error_log  logs/error.log;
#error_log  logs/error.log  notice;
#error_log  logs/error.log  info;

#pid        logs/nginx.pid;
events {
    worker_connections  1024;
    debug_connection 127.0.0.1;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    #tcp_nopush     on;

    #keepalive_timeout  0;
    keepalive_timeout  65;

    #gzip  on;

    server {
        listen       80;
        server_name  localhost;

        #charset koi8-r;

        #access_log  logs/host.access.log  main;

        location / {
            proxy_pass http://www.ai-as.net/;
        }
        
        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   html;
        }
    }

}

143|通过debug日志定位问题