resurfaceio-logger-lua

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

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:

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

resurfaceio/logger-lua