{"id":13636682,"url":"https://github.com/cloudflare/lua-resty-logger-socket","last_synced_at":"2025-04-07T17:07:21.856Z","repository":{"id":11190097,"uuid":"13570050","full_name":"cloudflare/lua-resty-logger-socket","owner":"cloudflare","description":"Raw-socket-based Logger Library for Nginx (based on ngx_lua)","archived":false,"fork":false,"pushed_at":"2024-09-21T21:11:26.000Z","size":136,"stargazers_count":488,"open_issues_count":34,"forks_count":130,"subscribers_count":39,"default_branch":"master","last_synced_at":"2024-10-29T19:58:55.398Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-10-14T18:52:26.000Z","updated_at":"2024-09-29T18:04:33.000Z","dependencies_parsed_at":"2024-01-13T11:52:43.353Z","dependency_job_id":"a4ee3198-75b5-41b7-96f7-f756211624db","html_url":"https://github.com/cloudflare/lua-resty-logger-socket","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Flua-resty-logger-socket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Flua-resty-logger-socket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Flua-resty-logger-socket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Flua-resty-logger-socket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/lua-resty-logger-socket/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247694875,"owners_count":20980733,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-02T00:01:04.025Z","updated_at":"2025-04-07T17:07:21.821Z","avatar_url":"https://github.com/cloudflare.png","language":"Raku","funding_links":[],"categories":["Libraries","Third Modules","Rust Modules"],"sub_categories":["C Modules","Lua Modules"],"readme":"Name\n====\n\nlua-resty-logger-socket - nonblocking remote access logging for Nginx\n\nTable of Contents\n=================\n\n* [Name](#name)\n* [Status](#status)\n* [Description](#description)\n* [Synopsis](#synopsis)\n* [Methods](#methods)\n    * [init](#init)\n    * [initted](#initted)\n    * [log](#log)\n    * [flush](#flush)\n* [Installation](#installation)\n* [TODO](#todo)\n* [Authors](#authors)\n* [Copyright and License](#copyright-and-license)\n\nStatus\n======\n\nThis library is still experimental and under early development.\n\nDescription\n===========\n\nThis lua library is a remote logging module for ngx_lua:\n\nhttp://wiki.nginx.org/HttpLuaModule\n\nThis is aimed to replace Nginx's standard [ngx_http_log_module](http://nginx.org/en/docs/http/ngx_http_log_module.html) to push access logs to a remote server via an nonblocking socket. A common remote log server supporting sockets is [syslog-ng](http://www.balabit.com/network-security/syslog-ng).\n\nThis Lua library takes advantage of ngx_lua's cosocket API, which ensures\n100% nonblocking behavior.\n\nSynopsis\n========\n\n```lua\n    lua_package_path \"/path/to/lua-resty-logger-socket/lib/?.lua;;\";\n\n    server {\n        location / {\n            log_by_lua '\n                local logger = require \"resty.logger.socket\"\n                if not logger.initted() then\n                    local ok, err = logger.init{\n                        host = 'xxx',\n                        port = 1234,\n                        flush_limit = 1234,\n                        drop_limit = 5678,\n                    }\n                    if not ok then\n                        ngx.log(ngx.ERR, \"failed to initialize the logger: \",\n                                err)\n                        return\n                    end\n                end\n\n                -- construct the custom access log message in\n                -- the Lua variable \"msg\"\n\n                local bytes, err = logger.log(msg)\n                if err then\n                    ngx.log(ngx.ERR, \"failed to log message: \", err)\n                    return\n                end\n            ';\n        }\n    }\n```\n\n[Back to TOC](#table-of-contents)\n\nMethods\n=======\n\nThis 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.\n\n[Back to TOC](#table-of-contents)\n\ninit\n----\n`syntax: ok, err = logger.init(user_config)`\n\nInitialize logger with user configurations. This logger must be initted before use. If you do not initialize the logger, you will get an error.\n\nAvailable user configurations are listed as follows:\n\n* `flush_limit`\n\n    If the buffered messages' size plus the current message size reaches (`\u003e=`) this limit (in bytes), the buffered log messages will be written to log server. Default to 4096 (4KB).\n\n* `drop_limit`\n\n    If the buffered messages' size plus the current message size is larger than this limit (in bytes), the current log message will be dropped because of limited buffer size. Default drop_limit is 1048576 (1MB).\n\n* `timeout`\n\n    Sets the timeout (in ms) protection for subsequent operations, including the *connect* method. Default value is 1000 (1 sec).\n\n* `host`\n\n    log server host.\n\n* `port`\n\n    log server port number.\n\n* `sock_type`\n\n    IP protocol type to use for transport layer. Can be either \"tcp\" or \"udp\". Default is \"tcp\".\n\n* `path`\n\n    If the log server uses a stream-typed unix domain socket, `path` is the socket file path. Note that host/port and path cannot both be empty. At least one must be supplied.\n\n* `max_retry_times`\n\n    Max number of retry times after a connect to a log server failed or send log messages to a log server failed.\n\n* `retry_interval`\n\n    The time delay (in ms) before retry to connect to a log server or retry to send log messages to a log server, default to 100 (0.1s).\n\n* `pool_size`\n\n    Keepalive pool size used by sock:keepalive. Default to 10.\n\n* `max_buffer_reuse`\n\n    Max number of reuse times of internal logging buffer before creating a new one (to prevent memory leak).\n\n* `periodic_flush`\n\n    Periodic flush interval (in seconds). Set to `nil` to turn off this feature.\n\n* `ssl`\n\n    Boolean, enable or disable connecting via SSL. Default to false.\n\n* `ssl_verify`\n\n    Boolean, enable or disable verifying host and certificate match. Default to true.\n\n* `sni_host`\n\n    Set the hostname to send in SNI and to use when verifying certificate match.\n\n[Back to TOC](#table-of-contents)\n\ninitted\n--------\n`syntax: initted = logger.initted()`\n\nGet a boolean value indicating whether this module has been initted (by calling the [init](#init) method).\n\n[Back to TOC](#table-of-contents)\n\nlog\n---\n`syntax: bytes, err = logger.log(msg)`\n\nLog 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.\n`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.\n\n[Back to TOC](#table-of-contents)\n\nflush\n-----\n`syntax: bytes, err = logger.flush()`\n\nFlushes any buffered messages out to remote immediately. Usually you do not need\nto call this manually because flushing happens automatically when the buffer is full.\n\n[Back to TOC](#table-of-contents)\n\nInstallation\n============\n\nYou need to compile at least [ngx_lua 0.9.0](https://github.com/chaoslawful/lua-nginx-module/tags) with your Nginx.\n\nYou need to configure\nthe [lua_package_path](https://github.com/chaoslawful/lua-nginx-module#lua_package_path) directive to\nadd the path of your `lua-resty-logger-socket` source tree to ngx_lua's Lua module search path, as in\n\n    # nginx.conf\n    http {\n        lua_package_path \"/path/to/lua-resty-logger-socket/lib/?.lua;;\";\n        ...\n    }\n\nand then load the library in Lua:\n\n    local logger = require \"resty.logger.socket\"\n\n[Back to TOC](#table-of-contents)\n\nTODO\n====\n\n* Multiple log server sharding and/or failover support.\n* \"match_similar\" utf8 support test.\n\n[Back to TOC](#table-of-contents)\n\nAuthors\n=======\n\nJiale Zhi \u003cvipcalio@gmail.com\u003e, CloudFlare Inc.\n\nYichun Zhang (agentzh) \u003cagentzh@gmail.com\u003e, CloudFlare Inc.\n\n[Back to TOC](#table-of-contents)\n\nCopyright and License\n=====================\n\nThis module is licensed under the BSD license.\n\nCopyright (C) 2013, by Jiale Zhi \u003cvipcalio@gmail.com\u003e, CloudFlare Inc.\n\nCopyright (C) 2013, by Yichun Zhang \u003cagentzh@gmail.com\u003e, CloudFlare Inc.\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n\n* 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.\n\nTHIS 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.\n\n[Back to TOC](#table-of-contents)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Flua-resty-logger-socket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Flua-resty-logger-socket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Flua-resty-logger-socket/lists"}