updated the docs for log_by_lua and log_by_lua_file.
This commit is contained in:
agentzh (章亦春)
Родитель
285b72716e
Коммит
1bf725345b
165
README
165
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>*
|
||||
|
||||
|
|
@ -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 <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](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 <path-to-lua-script-file>*
|
||||
|
||||
**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
|
||||
---------------------
|
||||
|
||||
|
|
@ -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>''
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче