Skip to content

Latest commit

 

History

History
318 lines (229 loc) · 9.66 KB

errlog.md

File metadata and controls

318 lines (229 loc) · 9.66 KB
Raw

Name

ngx.errlog - manage nginx error log data in Lua for OpenResty/ngx_lua.

Table of Contents

Status

This Lua module is currently considered experimental.

The API is still in flux and may change in the future without notice.

Synopsis

Capturing nginx error logs with specified log filtering level

error logs/error.log info;

http {
    # enable capturing error logs
    lua_capture_error_log 32m;

    init_by_lua_block {
        local errlog = require "ngx.errlog"
        local status, err = errlog.set_filter_level(ngx.WARN)
        if not status then
            ngx.log(ngx.ERR, err)
            return
        end
        ngx.log(ngx.WARN, "set error filter level: WARN")
    }

    server {
        # ...
        location = /t {
            content_by_lua_block {
                local errlog = require "ngx.errlog"
                ngx.log(ngx.INFO, "test1")
                ngx.log(ngx.WARN, "test2")
                ngx.log(ngx.ERR, "test3")

                local logs, err = errlog.get_logs(10)
                if not logs then
                    ngx.say("FAILED ", err)
                    return
                end

                for i = 1, #logs, 3 do
                    ngx.say("level: ", logs[i], " time: ", logs[i + 1],
                            " data: ", logs[i + 2])
                end
            }
        }
    }
}

The example location above produces a response like this:

level: 5 time: 1498546995.304 data: 2017/06/27 15:03:15 [warn] 46877#0:
    [lua] init_by_lua:8: set error filter level: WARN
level: 5 time: 1498546999.178 data: 2017/06/27 15:03:19 [warn] 46879#0: *1
    [lua] test.lua:5: test2, client: 127.0.0.1, server: localhost, ......
level: 4 time: 1498546999.178 data: 2017/06/27 15:03:19 [error] 46879#0: *1
    [lua] test.lua:6: test3, client: 127.0.0.1, server: localhost, ......

Back to TOC

Methods

set_filter_level

syntax: status, err = log_module.set_filter_level(log_level)

context: init_by_lua*

Specifies the filter log level, only to capture and buffer the error logs with a log level no lower than the specified level.

If we don't call this API, all of the error logs will be captured by default.

In case of error, nil will be returned as well as a string describing the error.

This API should always work with directive lua_capture_error_log.

See Nginx log level constants for all nginx log levels.

For example,

 init_by_lua_block {
     local errlog = require "ngx.errlog"
     errlog.set_filter_level(ngx.WARN)
 }

NOTE: The debugging logs since when OpenResty or NGINX is not built with --with-debug, all the debug level logs are suppressed regardless.

Back to TOC

get_logs

syntax: res, err = log_module.get_logs(max?, res?)

context: any

Fetches the captured nginx error log messages if any in the global data buffer specified by ngx_lua's lua_capture_error_log directive. Upon return, this Lua function also removes those messages from that global capturing buffer to make room for future new error log data.

In case of error, nil will be returned as well as a string describing the error.

The optional max argument is a number that when specified, will prevent errlog.get_logs from adding more than max messages to the res array.

for i = 1, 20 do
   ngx.log(ngx.ERR, "test")
end

local errlog = require "ngx.errlog"
local res = errlog.get_logs(10)
-- the number of messages in the `res` table is 10 and the `res` table
-- has 30 elements.

The resulting table has the following structure:

{ level1, time1, msg1, level2, time2, msg2, ... }

The levelX values are constants defined below:

https://github.com/openresty/lua-nginx-module/#nginx-log-level-constants

The timeX values are UNIX timestamps in seconds with millisecond precision. The sub-second part is presented as the decimal part. The time format is exactly the same as the value returned by ngx.now. It is also subject to NGINX core's time caching.

The msgX values are the error log message texts.

So to traverse this array, the user can use a loop like this:

for i = 1, #res, 3 do
    local level = res[i]
    if not level then
        break
    end

    local time = res[i + 1]
    local msg = res[i + 2]

    -- handle the current message with log level in `level`,
    -- log time in `time`, and log message body in `msg`.
end

Specifying max <= 0 disables this behavior, meaning that the number of results won't be limited.

The optional 2th argument res can be a user-supplied Lua table to hold the result instead of creating a brand new table. This can avoid unnecessary table dynamic allocations on hot Lua code paths. It is used like this:

local errlog = require "ngx.errlog"
local new_tab = require "table.new"

local buffer = new_tab(100 * 3, 0)  -- for 100 messages

local errlog = require "ngx.errlog"
local res, err = errlog.get_logs(0, buffer)
if res then
    -- res is the same table as `buffer`
    for i = 1, #res, 3 do
        local level = res[i]
        if not level then
            break
        end
        local time = res[i + 1]
        local msg  = res[i + 2]
        ...
    end
end

When provided with a res table, errlog.get_logs won't clear the table for performance reasons, but will rather insert a trailing nil value after the last table element.

When the trailing nil is not enough for your purpose, you should clear the table yourself before feeding it into the errlog.get_logs function.

Back to TOC

get_sys_filter_level

syntax: log_level = log_module.get_sys_filter_level()

context: any

Return the nginx core's error log filter level (defined via the error_log configuration directive in nginx.conf) as an integer value matching the nginx error log level constants documented below:

https://github.com/openresty/lua-nginx-module/#nginx-log-level-constants

For example:

local errlog = require "ngx.errlog"
local log_level = errlog.get_sys_filter_level()
-- Now the filter level is always one level higher than system default log level on priority
local status, err = errlog.set_filter_level(log_level - 1)
if not status then
    ngx.log(ngx.ERR, err)
    return
end

Back to TOC

Community

Back to TOC

English Mailing List

The openresty-en mailing list is for English speakers.

Back to TOC

Chinese Mailing List

The openresty mailing list is for Chinese speakers.

Back to TOC

Bugs and Patches

Please report bugs or submit patches by

  1. creating a ticket on the GitHub Issue Tracker,
  2. or posting to the OpenResty community.

Back to TOC

Author

Yuansheng Wang <[email protected]> (membphis), OpenResty Inc.

Back to TOC

Copyright and License

This module is licensed under the BSD license.

Copyright (C) 2017, by Yichun "agentzh" Zhang, OpenResty Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Back to TOC

See Also

Back to TOC