Home

Awesome

Name

lua-resty-logger-socket - nonblocking remote access logging for Nginx

Table of Contents

Status

This library is still experimental and under early development.

Description

This lua library is a remote logging module for ngx_lua:

http://wiki.nginx.org/HttpLuaModule

This is aimed to replace Nginx's standard ngx_http_log_module to push access logs to a remote server via an nonblocking socket. A common remote log server supporting sockets is syslog-ng.

This Lua library takes advantage of ngx_lua's cosocket API, which ensures 100% nonblocking behavior.

Synopsis

    lua_package_path "/path/to/lua-resty-logger-socket/lib/?.lua;;";

    server {
        location / {
            log_by_lua '
                local logger = require "resty.logger.socket"
                if not logger.initted() then
                    local ok, err = logger.init{
                        host = 'xxx',
                        port = 1234,
                        flush_limit = 1234,
                        drop_limit = 5678,
                    }
                    if not ok then
                        ngx.log(ngx.ERR, "failed to initialize the logger: ",
                                err)
                        return
                    end
                end

                -- construct the custom access log message in
                -- the Lua variable "msg"

                local bytes, err = logger.log(msg)
                if err then
                    ngx.log(ngx.ERR, "failed to log message: ", err)
                    return
                end
            ';
        }
    }

Back to TOC

Methods

This logger module is designed to be shared inside an Nginx worker process by all the requests. So currently only one remote log server is supported. We may support multiple log server sharding in the future.

Back to TOC

init

syntax: ok, err = logger.init(user_config)

Initialize logger with user configurations. This logger must be initted before use. If you do not initialize the logger, you will get an error.

Available user configurations are listed as follows:

Back to TOC

initted

syntax: initted = logger.initted()

Get a boolean value indicating whether this module has been initted (by calling the init method).

Back to TOC

log

syntax: bytes, err = logger.log(msg)

Log a message. By default, the log message will be buffered in the logger module until flush_limit is reached in which case the logger will flush all the buffered messages to remote log server via a socket. bytes is the number of bytes that successfully buffered in the logger. If bytes is nil, err is a string describing what kind of error happens this time. If bytes is not nil, then err is a previous error message. err can be nil when bytes is not nil.

Back to TOC

flush

syntax: bytes, err = logger.flush()

Flushes any buffered messages out to remote immediately. Usually you do not need to call this manually because flushing happens automatically when the buffer is full.

Back to TOC

Installation

You need to compile at least ngx_lua 0.9.0 with your Nginx.

You need to configure the lua_package_path directive to add the path of your lua-resty-logger-socket source tree to ngx_lua's Lua module search path, as in

# nginx.conf
http {
    lua_package_path "/path/to/lua-resty-logger-socket/lib/?.lua;;";
    ...
}

and then load the library in Lua:

local logger = require "resty.logger.socket"

Back to TOC

TODO

Back to TOC

Authors

Jiale Zhi vipcalio@gmail.com, CloudFlare Inc.

Yichun Zhang (agentzh) agentzh@gmail.com, CloudFlare Inc.

Back to TOC

Copyright and License

This module is licensed under the BSD license.

Copyright (C) 2013, by Jiale Zhi vipcalio@gmail.com, CloudFlare Inc.

Copyright (C) 2013, by Yichun Zhang agentzh@gmail.com, CloudFlare 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:

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