NAME

Log::Munger::LogProcessor - Compiles rule files and matches log records against them.

VERSION

Version 0.0.1

SYNOPSIS

use Log::Munger::LogProcessor;

my $processor = Log::Munger::LogProcessor->new( 'rules' => [ 'base', 'postfix' ] );

my $fields = $processor->process_item( 'item' => $decoded_log_hashref );
if ( defined($fields) ) {
    # $fields is a hashref of the named captures from the first matching rule
}

Each named rule file is loaded and its rules: section compiled into an ordered, merged dispatch list. A rule file with no rules: section (a pure primitive library such as base) is accepted and skipped for dispatch.

A rule dispatches when all of its gates pass and one of its patterns matches the target field. A gate passes when its field matches any of the gate's values, patterns are first-match-wins, and rules are tried in load order (files in the order given, rules in file order).

METHODS

new

Loads and compiles the named rule files.

- rules :: Rule files to load. The taken value is an array ref.
    Default :: undef (required)

- geoip :: Path to a MaxMind .mmdb database. When given, rules may flag
    captured fields (via a rule-level or file-level C<geoip:> list) whose
    values are looked up and stored under C<< $result->{geoip}{$field} >>.
    Requires IP::Geolocation::MMDB (a soft dependency, only loaded when this
    option is used).
    Default :: undef (geoip disabled)

process_item

Runs an item through the compiled rules and returns the named captures of the first matching rule.

The item may be given directly with item, or assembled from the individual syslog fields with message (plus the optional program / priority / facility). This lets a caller that already has the fields split out (a syslog reader, baphomet, etc.) hand them over without building the record hash itself.

- item :: The decoded log record (a hash ref), or a bare string. A bare
    string is treated as a raw log line and matched as the C<MESSAGE> field,
    so callers feeding whole log lines (e.g. apache/nginx access logs) need
    not wrap them. If given, C<item> takes precedence and the C<message> /
    C<program> / C<priority> / C<facility> args below are ignored.
    Default :: undef

- message :: The raw log message; assembled into C<< { MESSAGE => ... } >>.
    Default :: undef

- program :: Adds a C<PROGRAM> field (the usual gate for daemon rule files).
    Default :: undef

- priority :: Adds a C<PRIORITY> field.
    Default :: undef

- facility :: Adds a C<FACILITY> field.
    Default :: undef

my $fields = $processor->process_item( 'item' => $decoded_hashref );
my $fields = $processor->process_item( 'message' => $line, 'program' => 'sshd' );

Returns a hash ref of the winning pattern's named captures on a match (which may be an empty hash ref if the pattern had no named captures), or undef if no rule matched. This method never dies: an exception during matching is caught and comes back as undef. That bounds failures, not runtime -- a pattern prone to catastrophic backtracking can still burn CPU on a hostile line, so keep patterns anchored and tested.

explain_item

Like "process_item" but returns match metadata instead of just the fields, for tooling that needs to know which rule fired. Accepts the same arguments as "process_item" (item, or message plus optional program / priority / facility). Returns a hash ref:

{ matched => 0 }                                         # nothing matched
{ matched => 1, rule => <name>, pattern => <index>,
  field => <target field>, fields => { ...captures... } } # a rule fired

Never dies.

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The GNU Lesser General Public License, Version 3, June 2007