resurfaceio-logger-lua

Easily log API requests and responses to your own security data lake.

Contents

• Dependencies
• Installing With Luarocks
• Logging From NGINX
• Logging With API
• Development
• Testing Logger
• Protecting User Privacy

Dependencies

Requires Lua 5.1/LuaJIT as well as the following essential packages:

• ngx
• lua-cjson
• lua-ffi-zlib
• lua-resty-http

Installing With Luarocks

luarocks install resurfaceio-logger

Logging From NGINX

You might need to modify your lua_package_path and lua_package_cpath so that OpenResty looks for packages installed using luarocks.

• Install using luarocks.
• Add the following directives to the http context:

init_by_lua_block {
    local r = require "resurfaceio-logger"
    r.HttpLoggerForNginx.init{
        url="http://127.0.0.1:7701/message",
        rules="include debug"
    }
}
lua_need_request_body on;
access_by_lua_block {
    local r = require "resurfaceio-logger"
    r.HttpLoggerForNginx.access()
}

body_filter_by_lua_block {
    local r = require "resurfaceio-logger"
    r.HttpLoggerForNginx.bodyfilter()
}

log_by_lua_block {
    local r = require "resurfaceio-logger"
    r.HttpLoggerForNginx.log()
}

Example nginx.conf file:

http {
    lua_package_path '/usr/local/share/lua/5.1/?.lua;/usr/local/lib/lua/5.1/?.lua;/home/pepper/.luarocks/share/lua/5.1/?.lua;'
    lua_package_cpath '/usr/local/lib/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/home/pepper/.luarocks/lib/lua/5.1/?.so;'
    init_by_lua_block {
        local r = require "resurfaceio-logger"
        r.HttpLoggerForNginx.init{
            url="http://127.0.0.1:7701/message",
            rules="include debug"
        }
    }
    
    lua_need_request_body on;
    access_by_lua_block {
        local r = require "resurfaceio-logger"
        r.HttpLoggerForNginx.access()
    }
    
    body_filter_by_lua_block {
        local r = require "resurfaceio-logger"
        r.HttpLoggerForNginx.bodyfilter()
    }
    
    log_by_lua_block {
        local r = require "resurfaceio-logger"
        r.HttpLoggerForNginx.log()
    }
    
    server {
        listen 8000;
        
        location / {
            root app/www;
        }
    }
}

Logging With API

Loggers can be directly integrated into your application using our API. This requires the most effort compared with the options described above, but also offers the greatest flexibility and control.

API documentation

Development

Install dev requirements.

luarocks install --only-deps resurfaceio-logger

Testing Logger

• If you are running OpenResty, you can do

  resty test/test.lua

• If you don't have OpenResty installed but you do have docker, you can do:

  docker build -t loggerlua:test . && docker run -it --rm loggerlua:test

  Two tests are skipped if you don't have Resurface up and running. If you would like to run those tests as well, and you have docker-compose, you can do:

  docker build -t loggerlua:test . &&  docker-compose up

  Wait for the tests to complete, and then

  docker-compose down --remove-orphans --volumes && docker rmi loggerlua:test

Protecting User Privacy

Loggers always have an active set of rules that control what data is logged and how sensitive data is masked. All of the examples above apply a predefined set of rules (include debug), but logging rules are easily customized to meet the needs of any application.

Logging rules documentation

---

© 2016-2024 Graylog, Inc.