updated the docs for log_by_lua and log_by_lua_file.

This commit is contained in:
agentzh (章亦春) 2012-06-08 16:54:04 +08:00
Родитель 285b72716e
Коммит 1bf725345b
3 изменённых файлов: 291 добавлений и 112 удалений

169
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,69 +677,6 @@ Directives
lua_code_cache "off" in "nginx.conf" to avoid repeatedly reloading
Nginx.
log_by_lua
syntax: *log_by_lua <lua-script-str>*
context: *http, server, location, location if*
phase: *log_phase*
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.
Note that similarly to header_filter_by_lua, 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)
Here is an example of gathering average data for
$upstream_response_time :
lua_shared_dict log_dict 5M;
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
';
}
log_by_lua_file
syntax: *log_by_lua <lua-script-str>*
context: *http, server, location, location if*
phase: *log_phase*
Equivalent to log_by_blua, except that the file specified by
"<path-to-lua-script-file>" contains the lua code to be executed.
header_filter_by_lua
syntax: *header_filter_by_lua <lua-script-str>*
@ -739,8 +685,10 @@ Directives
phase: *output-header-filter*
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:
filter.
Note that the following API functions are currently disabled within this
context:
* Output API functions (e.g., ngx.say and ngx.send_headers)
@ -749,6 +697,8 @@ Directives
* 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).
Here is an example of overriding a response header (or adding one if
absent) in our Lua header filter:
@ -775,6 +725,82 @@ Directives
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: *log*
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)
* 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).
Here is an example of gathering average data for
$upstream_response_time:
lua_shared_dict log_dict 5M;
location / {
proxy_pass http://mybackend;
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)
';
}
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")
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: *log*
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.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)

Просмотреть файл

@ -303,7 +303,12 @@ The code in `<lua-script-str>` can make [API calls](http://wiki.nginx.org/HttpLu
This directive is designed to execute short, fast running code blocks as 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](http://wiki.nginx.org/HttpLuaModule#ngx.say), [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), [echo](http://wiki.nginx.org/HttpEchoModule#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](http://wiki.nginx.org/HttpLuaModule#ngx.say) and [ngx.send_headers](http://wiki.nginx.org/HttpLuaModule#ngx.send_headers))
* Control API functions (e.g., [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit))
* Subrequest API functions (e.g., [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) and [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi))
* Cosocket API functions (e.g., [ngx.socket.tcp](http://wiki.nginx.org/HttpLuaModule#ngx.socket.tcp) and [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#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 the [ngx.var.VARIABLE](http://wiki.nginx.org/HttpLuaModule#ngx.var.VARIABLE) interface.
@ -622,11 +627,14 @@ header_filter_by_lua
**phase:** *output-header-filter*
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:
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:
* Output API functions (e.g., [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) and [ngx.send_headers](http://wiki.nginx.org/HttpLuaModule#ngx.send_headers))
* Control API functions (e.g., [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit))
* Subrequest API functions (e.g., [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) and [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi))
* Cosocket API functions (e.g., [ngx.socket.tcp](http://wiki.nginx.org/HttpLuaModule#ngx.socket.tcp) and [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#ngx.req.socket)).
Here is an example of overriding a response header (or adding one if absent) in our Lua header filter:
@ -654,6 +662,77 @@ When a relative path like `foo/bar.lua` is given, they will be turned into the a
This directive was first introduced in the `v0.2.1rc20` release.
log_by_lua
----------
**syntax:** *log_by_lua &lt;lua-script-str&gt;*
**context:** *http, server, location, location if*
**phase:** *log*
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](http://wiki.nginx.org/HttpLuaModule#ngx.say) and [ngx.send_headers](http://wiki.nginx.org/HttpLuaModule#ngx.send_headers))
* Control API functions (e.g., [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit))
* Subrequest API functions (e.g., [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) and [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi))
* Cosocket API functions (e.g., [ngx.socket.tcp](http://wiki.nginx.org/HttpLuaModule#ngx.socket.tcp) and [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#ngx.req.socket)).
Here is an example of gathering average data for [$upstream_response_time](http://wiki.nginx.org/HttpUpstreamModule#.24upstream_response_time):
lua_shared_dict log_dict 5M;
location / {
proxy_pass http://mybackend;
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)
';
}
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")
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 &lt;path-to-lua-script-file&gt;*
**context:** *http, server, location, location if*
**phase:** *log*
Equivalent to [log_by_lua](http://wiki.nginx.org/HttpLuaModule#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.5.0rc31` release.
lua_need_request_body
---------------------
@ -1259,20 +1338,20 @@ This option is set to `false` by default
location /other {
set $dog "$dog world";
echo "$uri dog: $dog";
}
set $dog "$dog world";
echo "$uri dog: $dog";
}
location /lua {
set $dog 'hello';
content_by_lua '
res = ngx.location.capture("/other",
{ share_all_vars = true });
ngx.print(res.body)
ngx.say(ngx.var.uri, ": ", ngx.var.dog)
';
}
';
}
Accessing location `/lua` gives
@ -1349,25 +1428,25 @@ The `ctx` option can be used to specify a custom Lua table to serve as the [ngx.
location /sub {
content_by_lua '
ngx.ctx.foo = "bar";
content_by_lua '
ngx.ctx.foo = "bar";
';
}
}
location /lua {
content_by_lua '
local ctx = {}
local ctx = {}
res = ngx.location.capture("/sub", { ctx = ctx })
ngx.say(ctx.foo);
ngx.say(ngx.ctx.foo);
';
ngx.say(ngx.ctx.foo);
';
}
Then request `GET /lua` gives
bar
bar
nil
@ -2772,9 +2851,8 @@ Specify `options` to control how the match operation will be performed. The foll
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)

Просмотреть файл

@ -287,7 +287,12 @@ The code in <code><lua-script-str></code> can make [[#Nginx API for Lua|API call
This directive is designed to execute short, fast running code blocks as 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.say]], [[#ngx.exec|ngx.exec]], [[HttpEchoModule#echo|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|ngx.say]] and [[#ngx.send_headers|ngx.send_headers]])
* Control API functions (e.g., [[#ngx.exit|ngx.exit]])
* Subrequest API functions (e.g., [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]])
* Cosocket API functions (e.g., [[#ngx.socket.tcp|ngx.socket.tcp]] and [[#ngx.req.socket|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 the [[#ngx.var.VARIABLE|ngx.var.VARIABLE]] interface.
@ -598,11 +603,14 @@ The Lua code cache can be temporarily disabled during development by switching [
'''phase:''' ''output-header-filter''
Uses Lua code specified in <code><lua-script-str></code> to define an output header filter. Note that the following API functions are currently disabled within this context:
Uses Lua code specified in <code><lua-script-str></code> to define an output header filter.
Note that the following API functions are currently disabled within this context:
* Output API functions (e.g., [[#ngx.say|ngx.say]] and [[#ngx.send_headers|ngx.send_headers]])
* Control API functions (e.g., [[#ngx.exit|ngx.exit]])
* Subrequest API functions (e.g., [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]])
* Cosocket API functions (e.g., [[#ngx.socket.tcp|ngx.socket.tcp]] and [[#ngx.req.socket|ngx.req.socket]]).
Here is an example of overriding a response header (or adding one if absent) in our Lua header filter:
@ -629,6 +637,75 @@ When a relative path like <code>foo/bar.lua</code> is given, they will be turned
This directive was first introduced in the <code>v0.2.1rc20</code> release.
== log_by_lua ==
'''syntax:''' ''log_by_lua <lua-script-str>''
'''context:''' ''http, server, location, location if''
'''phase:''' ''log''
Run the Lua source code inlined as the <code><lua-script-str></code> at the <code>log</code> 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|ngx.say]] and [[#ngx.send_headers|ngx.send_headers]])
* Control API functions (e.g., [[#ngx.exit|ngx.exit]])
* Subrequest API functions (e.g., [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]])
* Cosocket API functions (e.g., [[#ngx.socket.tcp|ngx.socket.tcp]] and [[#ngx.req.socket|ngx.req.socket]]).
Here is an example of gathering average data for [[HttpUpstreamModule#$upstream_response_time|$upstream_response_time]]:
<geshi lang="nginx">
lua_shared_dict log_dict 5M;
location / {
proxy_pass http://mybackend;
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)
';
}
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")
if nb and sum then
ngx.say("average upstream response time: ", sum / nb)
else
ngx.say("no data yet")
end
';
}
</geshi>
This directive was first introduced in the <code>v0.5.0rc31</code> release.
== log_by_lua_file ==
'''syntax:''' ''log_by_lua_file <path-to-lua-script-file>''
'''context:''' ''http, server, location, location if''
'''phase:''' ''log''
Equivalent to [[#log_by_lua|log_by_lua]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code to be executed.
When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
This directive was first introduced in the <code>v0.5.0rc31</code> release.
== lua_need_request_body ==
'''syntax:''' ''lua_need_request_body <on|off>''
@ -1212,20 +1289,20 @@ This option is set to <code>false</code> by default
<geshi lang="nginx">
location /other {
set $dog "$dog world";
echo "$uri dog: $dog";
}
set $dog "$dog world";
echo "$uri dog: $dog";
}
location /lua {
set $dog 'hello';
content_by_lua '
res = ngx.location.capture("/other",
{ share_all_vars = true });
ngx.print(res.body)
ngx.say(ngx.var.uri, ": ", ngx.var.dog)
';
}
';
}
</geshi>
Accessing location <code>/lua</code> gives
@ -1302,25 +1379,25 @@ The <code>ctx</code> option can be used to specify a custom Lua table to serve a
<geshi lang="nginx">
location /sub {
content_by_lua '
ngx.ctx.foo = "bar";
content_by_lua '
ngx.ctx.foo = "bar";
';
}
}
location /lua {
content_by_lua '
local ctx = {}
local ctx = {}
res = ngx.location.capture("/sub", { ctx = ctx })
ngx.say(ctx.foo);
ngx.say(ngx.ctx.foo);
';
ngx.say(ngx.ctx.foo);
';
}
</geshi>
Then request <code>GET /lua</code> gives
<geshi lang="text">
bar
bar
nil
</geshi>
@ -2674,9 +2751,8 @@ Specify <code>options</code> to control how the match operation will be performe
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)