Permalink
Browse files

updated the docs for log_by_lua and log_by_lua_file.

  • Loading branch information...
1 parent 285b727 commit 1bf725345b986e008908093a6880d374b09ef26c @agentzh agentzh committed Jun 8, 2012
Showing with 278 additions and 99 deletions.
  1. +84 −59 README
  2. +98 −20 README.markdown
  3. +96 −20 doc/HttpLuaModule.wiki
View
143 README
@@ -314,8 +314,17 @@ Directives
the Nginx event loop is blocked during code execution. Time consuming
code sequences should therefore be avoided.
- Note that I/O operations such as ngx.say, ngx.exec, echo and similar are
- not permitted within the context of this directive.
+ Note that the following API functions are currently disabled within this
+ context:
+
+ * Output API functions (e.g., ngx.say and ngx.send_headers)
+
+ * Control API functions (e.g., ngx.exit)
+
+ * Subrequest API functions (e.g., ngx.location.capture and
+ ngx.location.capture_multi)
+
+ * Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket).
In addition, note that this directive can only write out a value to a
single Nginx variable at a time. However, a workaround is possible using
@@ -668,18 +677,18 @@ Directives
lua_code_cache "off" in "nginx.conf" to avoid repeatedly reloading
Nginx.
- log_by_lua
- syntax: *log_by_lua <lua-script-str>*
+ header_filter_by_lua
+ syntax: *header_filter_by_lua <lua-script-str>*
context: *http, server, location, location if*
- phase: *log_phase*
+ phase: *output-header-filter*
- Uses Lua code specified in "<lua-script-str>" to create a lua log handler
- This does not replace the current access logs, but runs after.
+ Uses Lua code specified in "<lua-script-str>" to define an output header
+ filter.
- Note that similarly to header_filter_by_lua, the following API
- functions are currently disabled within this context:
+ Note that the following API functions are currently disabled within this
+ context:
* Output API functions (e.g., ngx.say and ngx.send_headers)
@@ -688,59 +697,47 @@ Directives
* Subrequest API functions (e.g., ngx.location.capture and
ngx.location.capture_multi)
- Here is an example of gathering average data for
- $upstream_response_time :
+ * Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket).
- lua_shared_dict log_dict 5M;
+ Here is an example of overriding a response header (or adding one if
+ absent) in our Lua header filter:
location / {
-
proxy_pass http://mybackend;
-
- log_by_lua '
- local upstream_time = tonumber(ngx.var.upstream_response_time)
-
- local sum = ngx.shared.log_dict:get("upstream_time-sum")
- sum = sum + upstream_time
- ngx.shared.log_dict:set("upstream_time-sum", sum)
- ngx.shared.log_dict:incr("upstream_time-nb", 1)
- ';
- }
-
- location /status {
- content_by_lua '
- local sum = ngx.shared.log_dict:get("upstream_time-sum")
- local nb = ngx.shared.log_dict:get("upstream_time-nb")
-
- if nb and sum then
- ngx.say("average upstream response time: ", sum / nb)
- end
- ';
+ header_filter_by_lua 'ngx.header.Foo = "blah"';
}
+ This directive was first introduced in the "v0.2.1rc20" release.
- log_by_lua_file
-
- syntax: *log_by_lua <lua-script-str>*
+ header_filter_by_lua_file
+ syntax: *header_filter_by_lua_file <path-to-lua-script-file>*
context: *http, server, location, location if*
- phase: *log_phase*
+ phase: *output-header-filter*
- Equivalent to log_by_blua, except that the file specified by
- "<path-to-lua-script-file>" contains the lua code to be executed.
+ Equivalent to header_filter_by_lua, except that the file specified by
+ "<path-to-lua-script-file>" contains the Lua code to be executed.
+ When a relative path like "foo/bar.lua" is given, they will be turned
+ into the absolute path relative to the "server prefix" path determined
+ by the "-p PATH" command-line option while starting the Nginx server.
- header_filter_by_lua
- syntax: *header_filter_by_lua <lua-script-str>*
+ This directive was first introduced in the "v0.2.1rc20" release.
+
+ log_by_lua
+ syntax: *log_by_lua <lua-script-str>*
context: *http, server, location, location if*
- phase: *output-header-filter*
+ phase: *log*
- Uses Lua code specified in "<lua-script-str>" to define an output header
- filter. Note that the following API functions are currently disabled
- within this context:
+ Run the Lua source code inlined as the "<lua-script-str>" at the "log"
+ request processing phase. This does not replace the current access logs,
+ but runs after.
+
+ Note that the following API functions are currently disabled within this
+ context:
* Output API functions (e.g., ngx.say and ngx.send_headers)
@@ -749,31 +746,60 @@ Directives
* Subrequest API functions (e.g., ngx.location.capture and
ngx.location.capture_multi)
- Here is an example of overriding a response header (or adding one if
- absent) in our Lua header filter:
+ * Cosocket API functions (e.g., ngx.socket.tcp and ngx.req.socket).
+
+ Here is an example of gathering average data for
+ $upstream_response_time:
+
+ lua_shared_dict log_dict 5M;
location / {
proxy_pass http://mybackend;
- header_filter_by_lua 'ngx.header.Foo = "blah"';
+
+ log_by_lua '
+ local log_dict = ngx.shared.log_dict
+ local upstream_time = tonumber(ngx.var.upstream_response_time)
+
+ local sum = log_dict:get("upstream_time-sum")
+ sum = sum + upstream_time
+ log_dict:set("upstream_time-sum", sum)
+
+ log_dict:add("upstream_time-nb", 0)
+ log_dict:incr("upstream_time-nb", 1)
+ ';
}
- This directive was first introduced in the "v0.2.1rc20" release.
+ location = /status {
+ content_by_lua '
+ local log_dict = ngx.shared.log_dict
+ local sum = log_dict:get("upstream_time-sum")
+ local nb = log_dict:get("upstream_time-nb")
- header_filter_by_lua_file
- syntax: *header_filter_by_lua_file <path-to-lua-script-file>*
+ if nb and sum then
+ ngx.say("average upstream response time: ", sum / nb)
+ else
+ ngx.say("no data yet")
+ end
+ ';
+ }
+
+ This directive was first introduced in the "v0.5.0rc31" release.
+
+ log_by_lua_file
+ syntax: *log_by_lua_file <path-to-lua-script-file>*
context: *http, server, location, location if*
- phase: *output-header-filter*
+ phase: *log*
- Equivalent to header_filter_by_lua, except that the file specified by
+ Equivalent to log_by_lua, except that the file specified by
"<path-to-lua-script-file>" contains the Lua code to be executed.
When a relative path like "foo/bar.lua" is given, they will be turned
into the absolute path relative to the "server prefix" path determined
by the "-p PATH" command-line option while starting the Nginx server.
- This directive was first introduced in the "v0.2.1rc20" release.
+ This directive was first introduced in the "v0.5.0rc31" release.
lua_need_request_body
syntax: *lua_need_request_body <on|off>*
@@ -1884,7 +1910,7 @@ Nginx API for Lua
different from arguments taking empty string values. "GET
/test?foo=&bar=" will give something like
- foo:
+ foo:
bar:
Empty key arguments are discarded. "GET /test?=hello&=world" will yield
@@ -1979,7 +2005,7 @@ Nginx API for Lua
different from arguments taking empty string values. "POST /test" with
request body "foo=&bar=" will return something like
- foo:
+ foo:
bar:
Empty key arguments are discarded. "POST /test" with body
@@ -2980,9 +3006,8 @@ Nginx API for Lua
i case insensitive mode (similar to Perl's /i modifier)
j enable PCRE JIT compilation, this requires PCRE 8.21+ which
- must be built with the --enable-jit option.
- for optimum performance, this option should always be used
- together with the 'o' option.
+ must be built with the --enable-jit option. for optimum performance,
+ this option should always be used together with the 'o' option.
first introduced in ngx_lua v0.3.1rc30.
m multi-line mode (similar to Perl's /m modifier)
Oops, something went wrong.

0 comments on commit 1bf7253

Please sign in to comment.