LogZilla

Lua rules

Lua rules provide advanced parsing and enrichment capabilities for complex data transformation scenarios. They execute custom logic to extract fields, apply conditional processing, and enrich events with contextual information.

When to use Lua rules

Vendor-specific formats that require multiple extractions.
Conditional logic to interpret message variants.
Field mappings, lookups, or normalization across sources.
Message reformatting to create consistent, readable content.
Context enrichment that adds durable, searchable tags.

Event object API

Lua rules operate on an event object with these key properties:

event.message - The original log message text
event.host - Source hostname or IP address
event.program - Program or service name
event.severity - Numeric severity level (0-7)
event.facility - Syslog facility code
event.user_tags - Table for custom searchable tags
event.extra_fields - Table for additional structured data

Available helper functions

LogZilla provides helper functions for common parsing tasks:

get_kv_parser(sep, delim, quote) - Creates key-value parser
starts_with(str, prefix) - Check string prefix
ends_with(str, suffix) - Check string suffix
get_port_name(port) - Convert port number to service name

Format examples

Lua rules are stored as .lua files in the rule directory. The following example shows a basic structure for parsing key-value pairs:

lua
-- Parse key-value pairs from messages like: srcip="192.168.1.10" dstip="8.8.8.8" action="accept"
local kv_parser = get_kv_parser(' ', '=', '"')

function process(event)
    -- Check if this looks like a key-value format
    if string.find(event.message, '="') then
        -- Set program name for identification
        event.program = "CustomApp"
        
        -- Parse all key-value pairs from the message
        local kvpairs = kv_parser:match(event.message)
        
        -- Convert parsed pairs to searchable user tags
        for key, value in pairs(kvpairs) do
            if key == "srcip" then
                event.user_tags["SrcIP"] = value
            elseif key == "dstip" then
                event.user_tags["DstIP"] = value
            elseif key == "action" then
                event.user_tags["Action"] = value
            end
        end
    end
end

For conditional tagging based on message content:

lua
function process(event)
    -- Only process events from specific sources
    if event.program == "MyApp" then
        -- Add severity tags based on message content
        if string.find(event.message, "ERROR") then
            event.user_tags["Severity"] = "High"
            event.user_tags["Alert"] = "Error Detected"
        elseif string.find(event.message, "WARN") then
            event.user_tags["Severity"] = "Medium"
            event.user_tags["Alert"] = "Warning"
        end
        
        -- Extract and tag IP addresses
        local ip_pattern = "(%d+%.%d+%.%d+%.%d+)"
        local ip = string.match(event.message, ip_pattern)
        if ip then
            event.user_tags["IP_Address"] = ip
        end
    end
end

How Lua rules work

The parsing engine evaluates installed rules in a defined order.
Each rule inspects the event and decides whether to act.
Rules can enrich events by writing into structured fields and tags.
Rules can perform controlled rewrites for consistency and clarity.
Rules can skip events that do not meet criteria without overhead.

The result is a normalized event with useful fields for search, dashboards, and triggers.

Common enrichment patterns

Add normalized tags, such as device role, location, or application.
Extract identifiers (for example, user, session, interface) into dedicated fields.
Convert vendor codes into readable labels.
Reconstruct terse messages into human-readable summaries when needed.

Authoring guidelines

Keep rule intent focused; split distinct concerns into separate rules.
Prefer stable, low-cardinality tags for dashboards and filters.
Use consistent field names across apps to improve reuse.
Gate rules to the intended sources using dedicated inputs where applicable; see Syslog pipeline customization.

Managing rules via CLI

Refer to the CLI section for full syntax and options: Command Line Tools — Data Commands.

Typical operations include:

bash
# List rules and review status
logzilla rules list

# Validate or test a rule file before enabling
logzilla rules validate /path/to/rule.yaml
logzilla rules test --path /path/to/rule.yaml

# Enable, disable, or reload rules after changes
logzilla rules enable --name "My Lua Rule"
logzilla rules disable --name "My Lua Rule"
logzilla rules reload

# Review recent runtime errors for rules
logzilla rules errors

Performance and reliability

Narrow rule scope early to minimize unnecessary processing.
Avoid creating many high-cardinality tags; prefer normalized keys.
Monitor parser metrics and rule errors during rollouts.
Validate and test rules prior to enabling in production.

bash
# Parser overview and throughput
logzilla events parser-stats

# Field and tag insights
logzilla events values --scope fields --limit 50
logzilla events values --scope tags --limit 50

Safety and governance

Treat rules as configuration-as-code; review changes and track history.
Favor readability and stable behavior over clever parsing tricks.
Ensure sensitive data is not emitted as tags or message content.

Lua Rules