解剖Nginx·模块开发篇（5）解读内置非默认模块 ngx_http_stub_status_module
1 Background
ngx_http_stub_status_module 是一个 Nginx 的内置 HTTP 模块，该模块可以提供 Nginx 的状态信息。默认情况下这个模块是不被编译进来的，所以在编译 Nginx 时要指定加载该模块：
--with-http_stub_status_module
当然了，如果你是重新编译，仅仅-s reload是不够的，可能需要用到平滑升级：《高性能Web服务器Nginx的配置与部署研究（14）平滑升级你的Nginx》。
为什么拿它做例子？因为它也是个足够短小精悍的模块，是一个典型 handler 模块。那么以后我们讲解模块的过程，都是：
- 简要的介绍
- 使用的实例
- 指令介绍
- 源码分析
- 先上源码
- 分析
2 Simple example
location /nginx_status {
# copied from http://blog.kovyrin.net/2006/04/29/monitoring-nginx-with-rrdtool/
stub_status on;
access_log off;
allow SOME.IP.ADD.RESS;
deny all;
}
我们假设你是在本机上实验，并且开启的是 80 端口，那么在浏览器中输入：
http://localhost/nginx_status
会看到这样的信息：
Active connections: 291
server accepts handled requests
16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106
其含义很容易理解：
- 第一行
- 第二行
- 服务器已接受的连接数：16630948（accepted connection #）
- 服务器已处理的连接数：16630948（handled connection #）
- 服务器已处理的请求：31070465（可以算出，平均每个连接有 1.8 个请求）（handled connection #）
- 第三行
- Reading – Nginx 读取的请求头次数为 6；
- Writting – Nginx 读取请求体、处理请求并发送响应给客户端的次数为 179；
- Waiting – 当前活动的长连接数：106。
Nginx 官方的解释如下：
-
active connections– number of all open connections
-
server accepts handled requests– nginx accepted 16630948 connections, handled 16630948 connections (no one was closed just it was accepted), and handles 31070465 requests (1.8 requests per connection)
-
reading– nginx reads request header
-
writing– nginx reads request body, processes request, or writes response to a client
-
waiting– keep-alive connections, actually it is active - (reading + writing)
3 Directives
这个模块中的唯一一个指令，是：
stub_status
- 语法：
stub_status on
- 作用域：location
- 功能：统计这个 location 的信息。
4 Source analysis
先看完整代码：
/*
* Copyright (C) Igor Sysoev
* Copyright (C) Nginx, Inc.
*/
#include <ngx_config.h>
#include <ngx_core.h>
#include <ngx_http.h>
static char *ngx_http_set_status(ngx_conf_t *cf, ngx_command_t *cmd,
void *conf);
static ngx_command_t ngx_http_status_commands[] = {
{ ngx_string("stub_status"),
NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_FLAG,
ngx_http_set_status,
0,
0,
NULL },
ngx_null_command
};
static ngx_http_module_t ngx_http_stub_status_module_ctx = {
NULL, /* preconfiguration */
NULL, /* postconfiguration */
NULL, /* create main configuration */
NULL, /* init main configuration */
NULL, /* create server configuration */
NULL, /* merge server configuration */
NULL, /* create location configuration */
NULL /* merge location configuration */
};
ngx_module_t ngx_http_stub_status_module = {
NGX_MODULE_V1,
&ngx_http_stub_status_module_ctx, /* module context */
ngx_http_status_commands, /* module directives */
NGX_HTTP_MODULE, /* module type */
NULL, /* init master */
NULL, /* init module */
NULL, /* init process */
NULL, /* init thread */
NULL, /* exit thread */
NULL, /* exit process */
NULL, /* exit master */
NGX_MODULE_V1_PADDING
};
static ngx_int_t ngx_http_status_handler(ngx_http_request_t *r)
{
size_t size;
ngx_int_t rc;
ngx_buf_t *b;
ngx_chain_t out;
ngx_atomic_int_t ap, hn, ac, rq, rd, wr;
if (r->method != NGX_HTTP_GET && r->method != NGX_HTTP_HEAD) {
return NGX_HTTP_NOT_ALLOWED;
}
rc = ngx_http_discard_request_body(r);
if (rc != NGX_OK) {
return rc;
}
ngx_str_set(&r->headers_out.content_type, "text/plain");
if (r->method == NGX_HTTP_HEAD) {
r->headers_out.status = NGX_HTTP_OK;
rc = ngx_http_send_header(r);
if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
return rc;
}
}
size = sizeof("Active connections: \n") + NGX_ATOMIC_T_LEN
+ sizeof("server accepts handled requests\n") - 1
+ 6 + 3 * NGX_ATOMIC_T_LEN
+ sizeof("Reading: Writing: Waiting: \n") + 3 * NGX_ATOMIC_T_LEN;
b = ngx_create_temp_buf(r->pool, size);
if (b == NULL) {
return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
out.buf = b;
out.next = NULL;
ap = *ngx_stat_accepted;
hn = *ngx_stat_handled;
ac = *ngx_stat_active;
rq = *ngx_stat_requests;
rd = *ngx_stat_reading;
wr = *ngx_stat_writing;
b->last = ngx_sprintf(b->last, "Active connections: %uA \n", ac);
b->last = ngx_cpymem(b->last, "server accepts handled requests\n",
sizeof("server accepts handled requests\n") - 1);
b->last = ngx_sprintf(b->last, " %uA %uA %uA \n", ap, hn, rq);
b->last = ngx_sprintf(b->last, "Reading: %uA Writing: %uA Waiting: %uA \n",
rd, wr, ac - (rd + wr));
r->headers_out.status = NGX_HTTP_OK;
r->headers_out.content_length_n = b->last - b->pos;
b->last_buf = 1;
rc = ngx_http_send_header(r);
if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
return rc;
}
return ngx_http_output_filter(r, &out);
}
static char *ngx_http_set_status(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
ngx_http_core_loc_conf_t *clcf;
clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
clcf->handler = ngx_http_status_handler;
return NGX_CONF_OK;
}
的确够短小精悍吧？关键在于 Nginx 提供的模块扩展方式比较好，让你可以少写一些代码（NDK 可以让你写的更少，这是后话）。
4.1 模块定义 ngx_http_stub_status_module
ngx_module_t ngx_http_stub_status_module = {
NGX_MODULE_V1,
&ngx_http_stub_status_module_ctx, /* module context */
ngx_http_status_commands, /* module directives */
NGX_HTTP_MODULE, /* module type */
NULL, /* init master */
NULL, /* init module */
NULL, /* init process */
NULL, /* init thread */
NULL, /* exit thread */
NULL, /* exit process */
NULL, /* exit master */
NGX_MODULE_V1_PADDING
};
与此前介绍的 ngx_http_hello_world_module 并无本质区别。
4.2 命令集定义 ngx_http_status_commands
static ngx_command_t ngx_http_status_commands[] = {
{ ngx_string("stub_status"),
NGX_HTTP_SRV_CONF|NGX_HTTP_LOC_CONF|NGX_CONF_FLAG,
ngx_http_set_status,
0,
0,
NULL },
ngx_null_command
};
命令集定义如上，得到如下信息：
- name：stub_status
- type：server conf、location conf、conf flag，其中最后一个比较陌生，相似的取值有：
#define NGX_CONF_ARGS_NUMBER 0x000000ff#define NGX_CONF_BLOCK 0x00000100#define NGX_CONF_FLAG 0x00000200#define NGX_CONF_ANY 0x00000400#define NGX_CONF_1MORE 0x00000800#define NGX_CONF_2MORE 0x00001000#define NGX_CONF_MULTI 0x00002000
- set：ngx_http_set_status
下面解释下一些 types：
4.2.1 NGX_CONF_XXX
以下宏定义来自 ngx_conf_file.h：
#define NGX_CONF_NOARGS 0x00000001 // 命令不接受参数
#define NGX_CONF_TAKE1 0x00000002 // 命令携带1个参数
#define NGX_CONF_TAKE2 0x00000004 // 命令携带2个参数
#define NGX_CONF_TAKE3 0x00000008 // 命令携带3个参数
#define NGX_CONF_TAKE4 0x00000010 // 命令携带4个参数
#define NGX_CONF_TAKE5 0x00000020 // 命令携带5个参数
#define NGX_CONF_TAKE6 0x00000040 // 命令携带6个参数
#define NGX_CONF_TAKE7 0x00000080 // 命令携带7个参数
#define NGX_CONF_TAKE12 (NGX_CONF_TAKE1|NGX_CONF_TAKE2) // 命令携带1个或2个参数
#define NGX_CONF_TAKE13 (NGX_CONF_TAKE1|NGX_CONF_TAKE3) // 命令携带1个或3个参数
#define NGX_CONF_TAKE23 (NGX_CONF_TAKE2|NGX_CONF_TAKE3) // 命令携带2个或3个参数
#define NGX_CONF_TAKE123 (NGX_CONF_TAKE1|NGX_CONF_TAKE2|NGX_CONF_TAKE3) // 命令携带1个、2个或3个参数
#define NGX_CONF_TAKE1234 (NGX_CONF_TAKE1|NGX_CONF_TAKE2|NGX_CONF_TAKE3|NGX_CONF_TAKE4) // 命令携带1个、2个、3个或4个参数
#define NGX_CONF_ARGS_NUMBER 0x000000ff // 命令
#define NGX_CONF_BLOCK 0x00000100 // 块域，后面跟 {…}，比如 server {...}
#define NGX_CONF_FLAG 0x00000200 // 命令接受“on|off”参数
#define NGX_CONF_ANY 0x00000400
#define NGX_CONF_1MORE 0x00000800 // 命令携带至少1个参数
#define NGX_CONF_2MORE 0x00001000 // 命令携带至少2个参数
#define NGX_CONF_MULTI 0x00002000 // 命令携带多个参数
4.3 上下文定义 ngx_http_stub_status_module_ctx
static ngx_http_module_t ngx_http_stub_status_module_ctx = {
NULL, /* preconfiguration */
NULL, /* postconfiguration */
NULL, /* create main configuration */
NULL, /* init main configuration */
NULL, /* create server configuration */
NULL, /* merge server configuration */
NULL, /* create location configuration */
NULL /* merge location configuration */
};
这个都是 NULL，够简单，无话可说了⋯⋯
4.4 命令设置函数 ngx_http_set_status
static char *ngx_http_set_status(ngx_conf_t *cf, ngx_command_t *cmd, void *conf) {
ngx_http_core_loc_conf_t *clcf;
clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
clcf->handler = ngx_http_status_handler;
return NGX_CONF_OK;
}
和 ngx_http_hello_world_module 对比下：
static char* ngx_http_hello_world(ngx_conf_t* cf, ngx_command_t* cmd, void* conf) {
ngx_http_core_loc_conf_t* clcf;
clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);
clcf->handler = ngx_http_hello_world_handler;
ngx_conf_set_str_slot(cf, cmd, conf);
return NGX_CONF_OK;
}
唯一的区别，就是 ngx_http_hello_world_module 多了一句 ngx_conf_set_str_slot。这个先留做一个问题，后面会介绍，暂时与关键主题无关。
4.5 命令处理函数 ngx_http_status_handler
static ngx_int_t ngx_http_status_handler(ngx_http_request_t *r)
{
size_t size;
ngx_int_t rc;
ngx_buf_t *b;
ngx_chain_t out;
ngx_atomic_int_t ap, hn, ac, rq, rd, wr;
这个模块要求接受的请求类是 GET、HEAD，其他类型的请求会被拒绝。
if (r->method != NGX_HTTP_GET && r->method != NGX_HTTP_HEAD) {
return NGX_HTTP_NOT_ALLOWED;
}
放弃请求体，因为这个模块用不上。
rc = ngx_http_discard_request_body(r);
if (rc != NGX_OK) {
return rc;
}
如果请求是 HEAD 类型的，则直接设置响应头的 content_type、status 字段，并发送响应头。
ngx_str_set(&r->headers_out.content_type, "text/plain");
if (r->method == NGX_HTTP_HEAD) {
r->headers_out.status = NGX_HTTP_OK;
rc = ngx_http_send_header(r);
if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
return rc;
}
}
创建一个缓冲区，向缓冲区写入我们上面在浏览器中看到的东西。
size = sizeof("Active connections: \n") + NGX_ATOMIC_T_LEN
+ sizeof("server accepts handled requests\n") - 1
+ 6 + 3 * NGX_ATOMIC_T_LEN
+ sizeof("Reading: Writing: Waiting: \n") + 3 * NGX_ATOMIC_T_LEN;
b = ngx_create_temp_buf(r->pool, size);
if (b == NULL) {
return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
out.buf = b;
out.next = NULL;
ap = *ngx_stat_accepted;
hn = *ngx_stat_handled;
ac = *ngx_stat_active;
rq = *ngx_stat_requests;
rd = *ngx_stat_reading;
wr = *ngx_stat_writing;
// 封装了 sprintf
b->last = ngx_sprintf(b->last, "Active connections: %uA \n", ac);
// 封装了 memcpy
b->last = ngx_cpymem(b->last, "server accepts handled requests\n",
sizeof("server accepts handled requests\n") - 1);
b->last = ngx_sprintf(b->last, " %uA %uA %uA \n", ap, hn, rq);
b->last = ngx_sprintf(b->last, "Reading: %uA Writing: %uA Waiting: %uA \n",
rd, wr, ac - (rd + wr));
缓冲区写完了。然后设置下响应头的 status、content_length_n（还记得吗？b->last - b->pos 刚好是缓冲区的第二个区域，是已写入数据部分。）
r->headers_out.status = NGX_HTTP_OK;
r->headers_out.content_length_n = b->last - b->pos;
b->last_buf = 1;
发送响应头。
rc = ngx_http_send_header(r);
if (rc == NGX_ERROR || rc > NGX_OK || r->header_only) {
return rc;
}
filter。
return ngx_http_output_filter(r, &out);
}
5 Reference
- http://wiki.nginx.org/HttpStubStatusModule
- http://blog.csdn.net/lengzijian/article/details/7356064
- http://www.codinglabs.org/html/intro-of-nginx-module-development.html
6 本节留下的问题：
- ngx_conf_set_str_slot：你可以先去了解下，或者等待在后面的博文中看到 :)
-
转载请注明来自柳大的CSDN博客：Blog.CSDN.net/Poechant
-
分享到：
相关推荐
备用nginx代理模块
ngx_http_dav_ext_module.so centos7 nginx 1.18 可以作为模块加载
二. ngx_http_limit_conn_module指令解释limit_conn_zone语法: limit_conn_zone $variable zo
nginx1.20.2
ngx_req_status用来展示nginx请求状态信息，类似于apache的status，nginx自带的模块只能显示连接数等等信息，我们并不能知道到底有哪些请求、以及各url域名所消耗的带宽是多少。ngx_req_status提供了这些功能. 1、按...
nginx-1.24.0 含一些常用模块，如：ngx_http_status_module、http_autoindex_module 、limit_conn_module、ngx_http_limit_req_module、ngx_http_access_module、ngx_http_auth_basic_module、ngx_...
当Nginx作为文件下载服务的反向代理,用户请求一个非常大的文件的时候,它会一直占满反向代理服务器与后端主机之间的带宽。因为nginx一次获取整个...Configure nginx with--add-module=/path/to/ngx_http_subrange_module
lua-upstream-nginx-module, Nginx C 模块将Lua向ngx_lua公开，用于 Nginx upstreams 电子邮件名称ngx_http_lua_upstream - Nginx MODULE，用于向 Nginx upstreams公开Lua到 ngx_lua目录NAME状态概要说明函数get_...
http_stub_status_module http_flv_module http_mp4_module http_gunzip_module http_gzip_static_module http_auth_request_module http_random_index_module http_secure_link_module mail http_ssl_module mail_...
用于nginx的http正向代理https使用的模块
ngx_python 是为 nginx 嵌入 python 脚本的模块。环境- python 2.7.*- nginx-1.6.3 安装```sh git clone https://github.com/rryqszq4/ngx_python.git wget 'http://nginx.org/download/nginx-1.6.3.tar.gz' ...
ngx_kafka_module, Nginx Kafka 模块，将日志日志数据发送到 Kafka 群集 Nginx Kafka 模块 Nginx Kafka MODULE 用于接收 HTTP POST 数据并向 Kafka 传递消息。如果使用这里 MODULE 时存在任何问题，请随时向我发送...
ngx_http_captcha_module 说明： 此nginx模块可直接生成验证码和验证验证码，可在nginx配置中自定义验证码大小、长度、字体、过期时间等。此项目无需版权，可自由下载使用或二次开发。 安装方法： 1. $ cp ngx_...
ngx_http_hls_module Nginx HLS 模块，兼容直播和点播服务.
nginx lua module for windows 详细请访问 http://blog.csdn.net/ngwsx/
Nginx：一致性哈希（第三方模块ngx_http_consistent_hash）：ngx_http_consistent_hash-master.zip
ngx_http_enhance_mp4_module 该模块是原始 nginx mp4 模块（附带在 nginx 源代码中）的增强版本。 请注意，这是我自己的项目，除了需要ngx_http_mp4_module所有源代码外，它与 nginx 的源代码没有任何关系。 该模块...
ngx_realtime_request是nginx用来统计虚拟主机流量的模块, 首先和大家说下这个模块是基于域名的，将会记录这个域名的请求量、发送字节、返回http状态码的数量，特性如下： 1、基于域名记录 2、记录请求数据量 3、...
ngx_cache_purge 是 nginx 模块，此模块可以清理 nginx 的 FastCGI、proxy、 SCGI 和 uWSGI 的缓存。配置指令（相同位置语法）fastcgi_cache_purgesyntax: fastcgi_cache_purge on|off|<method> [from all|<ip> [.....
ngx_sqlite 是嵌入 sqlite 数据库的 nginx 模块。通过强大的nginx server，可以使用http协议访问sqlite数据库。环境- sqlite 3- nginx-1.6.3 安装```sh $ git clone https://github.com/rryqszq4/ngx_sqlite.git...