1 Background

http://nginx.org/en/docs/http/ngx_http_stub_status_module.html

ngx_http_stub_status_module 是一個 Nginx 的內置 HTTP 模塊，該模塊可以提供 Nginx 的狀態信息。默認情況下這個模塊是不被編譯進來的，所以在編譯 Nginx 時要指定加載該模塊：

--with-http_stub_status_module

為什么拿它做例子？因為它也是個足夠短小精悍的模塊，是一個典型 handler 模塊。那么以后我們講解模塊的過程，都是：

1. 簡要的介紹
2. 使用的實例
3. 指令介紹
4. 源碼分析

2 Simple example

location /nginx_status {    stub_status on;    access_log   off;
 access_log /usr/local/nginx/logs/status.log;    #日志    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  

其含義很容易理解：

• 第一行
  

  • 當前的活躍連接數：291

• 第二行
  

  • 服務器已接受的連接數：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 requestsn") - 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 requestsn",                           sizeof("server accepts handled requestsn") - 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 requestsn") - 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 requestsn",                           sizeof("server accepts handled requestsn") - 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);  }