lua-resty-logger-socket

Nginx 的非阻塞远程访问日志记录

账户

p0pr0ck5

仓库

https://github.com/p0pr0ck5/lua-resty-logger-socket

$ opm get p0pr0ck5/lua-resty-logger-socket

名称

lua-resty-logger-socket - Nginx 的非阻塞远程访问日志记录

此库仍处于实验阶段，并处于早期开发中。

描述

此 Lua 库是 ngx_lua 的远程日志记录模块

http://wiki.nginx.org/HttpLuaModule

旨在替换 Nginx 的标准 ngx_http_log_module，通过非阻塞套接字将访问日志推送到远程服务器。一个常见的支持套接字的远程日志服务器是 syslog-ng。

此 Lua 库利用了 ngx_lua 的 cosocket API，确保了 100% 的非阻塞行为。

概要

        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
                ';
            }
        }

方法

此日志记录模块旨在由所有请求在 Nginx 工作进程内共享。因此，目前仅支持一个远程日志服务器。我们可能会在将来支持多个日志服务器分片。

初始化

语法：ok, err = logger.init(user_config)

使用用户配置初始化日志记录器。此日志记录器必须在使用前进行初始化。如果不初始化日志记录器，将出现错误。

可用的用户配置如下所示

flush_limit

如果缓冲消息的大小加上当前消息的大小达到（>=）此限制（以字节为单位），则将缓冲的日志消息写入日志服务器。默认为 4096（4KB）。

drop_limit

如果缓冲消息的大小加上当前消息的大小大于此限制（以字节为单位），则由于缓冲区大小有限，将丢弃当前日志消息。默认 drop_limit 为 1048576（1MB）。

超时

设置后续操作（包括连接方法）的超时（以毫秒为单位）保护。默认值为 1000（1 秒）。

主机

日志服务器主机。

端口

日志服务器端口号。

sock_type

用于传输层的 IP 协议类型。可以是“tcp”或“udp”。默认为“tcp”。

路径

如果日志服务器使用流类型的 Unix 域套接字，则path是套接字文件路径。请注意，host/port 和 path 不能都为空。必须至少提供一个。

max_retry_times

连接到日志服务器失败或发送日志消息到日志服务器失败后的最大重试次数。

retry_interval

连接到日志服务器或重试发送日志消息到日志服务器之前的延迟时间（以毫秒为单位），默认为 100（0.1 秒）。

pool_size

sock:keepalive 使用的保持活动池大小。默认为 10。

max_buffer_reuse

在创建新的内部日志缓冲区之前，内部日志缓冲区的最大重用次数（以防止内存泄漏）。

periodic_flush

定期刷新间隔（以秒为单位）。设置为nil以关闭此功能。

ssl

布尔值，启用或禁用通过 SSL 连接。默认为 false。

ssl_verify

布尔值，启用或禁用验证主机和证书匹配。默认为 true。

sni_host

设置要在 SNI 中发送以及在验证证书匹配时使用的主机名。

已初始化

语法：initted = logger.initted()

获取一个布尔值，指示此模块是否已初始化（通过调用init方法）。

日志

语法：bytes, err = logger.log(msg)

记录一条消息。默认情况下，日志消息将缓冲在日志记录器模块中，直到达到flush_limit，此时日志记录器将通过套接字将所有缓冲的消息刷新到远程日志服务器。bytes是成功缓冲在日志记录器中的字节数。如果bytes为 nil，则err是描述这次发生哪种错误的字符串。如果 bytes 不为 nil，则err是先前的错误消息。当bytes不为 nil 时，err可以为 nil。

刷新

语法：bytes, err = logger.flush()

立即将所有缓冲的消息刷新到远程。通常您不需要手动调用此方法，因为刷新会在缓冲区满时自动发生。

安装

您需要使用您的 Nginx 编译至少 ngx_lua 0.9.0。

您需要配置 lua_package_path 指令以将您的lua-resty-logger-socket源代码树的路径添加到 ngx_lua 的 Lua 模块搜索路径，如下所示

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

然后在 Lua 中加载库

    local logger = require "resty.logger.socket"

待办事项

多个日志服务器分片和/或故障转移支持。
“match_similar” utf8 支持测试。

作者

Jiale Zhi <vipcalio@gmail.com>，CloudFlare Inc。

Yichun Zhang (agentzh) <agentzh@gmail.com>，CloudFlare Inc。

版权和许可证

此模块根据 BSD 许可证发布。

在满足以下条件的情况下，允许以源代码和二进制形式重新分发和使用，无论是否修改：

源代码的再分发必须保留上述版权声明、此条件列表和以下免责声明。

二进制形式的再分发必须在随分发提供的文档和/或其他材料中复制上述版权声明、此条件列表和以下免责声明。

本软件由版权持有人和贡献者“按原样”提供，并且不提供任何明示或暗示的担保，包括但不限于适销性和特定用途适用性的暗示担保。在任何情况下，版权持有人或贡献者均不对任何直接、间接、附带、特殊、惩罚性或后果性损害（包括但不限于替代商品或服务的采购；使用、数据或利润损失；或业务中断）负责，无论这些损害是如何造成的以及基于何种责任理论，无论是合同、严格责任还是侵权行为（包括疏忽或其他），即使已被告知可能发生此类损害。

作者

Robert Paprocki (p0pr0ck5)

许可证

gpl3

版本

p0pr0ck5/lua-resty-logger-socket 0.03 作者： p0pr0ck5

Nginx 的非阻塞远程访问日志记录 2016-10-17 18:45:16