Atatus Plugin for NGINX

The Atatus NGINX Lua Plugin logs API calls to Atatus for API analytics and monitoring.
This plugin supports any NGINX Open Source that has OpenResty installed, including API gateways built on top of OpenResty.

How to Install

Ensure you have lua-nginx-module installed.
- If you’re running an OpenResty image, it’s already installed.
- If you’re using NGINX Plus, follow the official NGINX Plus Lua module setup
Install the Atatus LuaRock:

luarocks install --server=http://luarocks.org/manifests/atatus lua-resty-atatus

Configuration (Generic OpenResty)

Edit your nginx.conf to load the Atatus plugin. If needed, replace /usr/local/openresty/luajit/share/lua/5.1/resty with the correct Lua plugin installation path. You can find it using:

find / -name "atatus" -type d

Example Configuration

lua_shared_dict atatus_conf 5m;

init_by_lua_block {
    local config = ngx.shared.atatus_conf;
    config:set("x_atatus_license_key", "YOUR_LICENSE_KEY")

    local mo_client = require "atatusapi.lua.atatus_client"
    mo_client.get_atatus_client(ngx)
}

# Lua paths (update if needed)
lua_package_cpath ";;${prefix}?.so;${prefix}src/?.so;/usr/share/lua/5.1/lua/resty/atatus/?.so;/usr/share/lua/5.1/?.so;/usr/lib64/lua/5.1/?.so;/usr/lib/lua/5.1/?.so;/usr/local/openresty/luajit/share/lua/5.1/lua/resty?.so;/usr/local/share/lua/5.1/resty/atatus/?.so";
lua_package_path ";;${prefix}?.lua;${prefix}src/?.lua;/usr/share/lua/5.1/lua/resty/atatus/?.lua;/usr/share/lua/5.1/?.lua;/usr/lib64/lua/5.1/?.lua;/usr/lib/lua/5.1/?.lua;/usr/local/openresty/luajit/share/lua/5.1/lua/resty?.lua;/usr/local/share/lua/5.1/resty/atatus/?.lua";

server {
    listen 80;
    resolver 8.8.8.8;

    # Variables used by Atatus
    set $atatus_user_id nil;
    set $atatus_company_id nil;
    set $atatus_req_body nil;
    set $atatus_res_body nil;

    # Assign values from request headers
    header_filter_by_lua_block {
        ngx.var.atatus_user_id    = ngx.req.get_headers()["X-User-Id"]
        ngx.var.atatus_company_id = ngx.req.get_headers()["X-Company-Id"]
    }

    # Atatus Lua hooks
    access_by_lua_file /usr/local/openresty/luajit/share/lua/5.1/resty/atatus/read_req_body.lua;
    body_filter_by_lua_file /usr/local/openresty/luajit/share/lua/5.1/resty/atatus/read_res_body.lua;
    log_by_lua_file   /usr/local/openresty/luajit/share/lua/5.1/resty/atatus/send_event.lua;

    # Sample API
    location /api {
        add_header Content-Type "application/json";
        return 200 '{"message": "Hello World", "completed": true}';
    }
}

Important: NGINX supports log_by_lua* only once in the same section. If your configuration already uses the same NGINX directives as Atatus, adjust accordingly. see OpenResty docs

Configuration Options

Static Options (set at startup in init_by_lua_block)

Option	Description	Type	Default
`x_atatus_license_key`	Required License Key for authentication.	`string`	-
`disable_capture_request_body`	Disable request body logging.	`boolean`	`false`
`disable_capture_response_body`	Disable response body logging.	`boolean`	`false`
`request_header_masks`	Comma-separated request header fields to mask.	`string`	-
`request_body_masks`	Comma-separated request body fields to mask.	`string`	-
`response_header_masks`	Comma-separated response header fields to mask.	`string`	-
`response_body_masks`	Comma-separated response body fields to mask.	`string`	-
`request_query_masks`	Comma-separated query string params to mask.	`string`	-
`disable_transaction_id`	Prevent `X-Atatus-Transaction-Id` header.	`boolean`	`false`
`debug`	Enable debug logs.	`boolean`	`false`
`authorization_header_name`	Header(s) to identify the User.	`string`	`"authorization"`
`authorization_user_id_field`	Field in auth header for User ID.	`string`	`"sub"`
`authorization_company_id_field`	Field in auth header for Company ID.	`string`	-
`batch_size`	Max batch size when sending to Atatus.	`number`	`50`
`request_max_body_size_limit`	Max request body size in bytes.	`number`	`100000`
`response_max_body_size_limit`	Max response body size in bytes.	`number`	`100000`
`enable_compression`	Compress requests before sending.	`boolean`	`false`

Dynamic Variables (set per request)

Set these variables in ngx.var (e.g., in header_filter_by_lua_block or body_filter_by_lua_block):

Variable	Description	Type
`atatus_user_id`	Attribute API requests to users.	`string`
`atatus_company_id`	Attribute API requests to companies/accounts.	`string`
`atatus_api_version`	Tag request with an API version.	`string`
`atatus_log_event`	Skip logging when set to `false`.	`boolean`

Example:

header_filter_by_lua_block {
    ngx.var.atatus_user_id     = ngx.req.arg_user_id
    ngx.var.atatus_api_version = ngx.req.get_headers()["X-API-Version"]
}

body_filter_by_lua_block {
    ngx.var.atatus_company_id = ngx.resp.get_headers()["X-Company-Id"]
}

Troubleshooting

Response body not logged

If response bodies are not being captured in Atatus, your setup may require an internal proxy_pass. Without proxy_pass:

location /api {
    add_header Content-Type "application/json";
    return 200 '{"message": "Hello World", "completed": true}';
}

With proxy_pass:

location /api {
    proxy_pass http://127.0.0.1:80/internal;
}

location /internal {
    add_header Content-Type "application/json";
    return 200 '{"message": "Hello World", "completed": true}';
}

​How to Install

​Configuration (Generic OpenResty)

​Example Configuration

​Configuration Options

​Dynamic Variables (set per request)

​Example:

​Troubleshooting

How to Install

Configuration (Generic OpenResty)

Example Configuration

Configuration Options

Dynamic Variables (set per request)

Example:

Troubleshooting