Log Parser XML Reference

This page provides a complete reference for the log parser XML definition format used by the Log Watch subagent.

For how to set up and use log monitoring, see Log Monitoring.

Parser Element

The root <parser> element accepts these attributes:

Attribute Default Description

name

Parser name (for reference in metrics and logging)

processAll

false

Process all rules even after a match (default: stop at first match)

checkInterval

10000

File check interval in milliseconds

lastRecordTimeout

0

Time in milliseconds to wait for a newline before processing an incomplete last line as a complete record (0 = wait for newline)

File Element

The <file> element specifies the log file to monitor. If the file name starts with *, the rest of the name is treated as a Windows Event Log channel name instead of a file path (e.g., *Security); this form works on Windows only.

Attribute Description

encoding

File encoding: auto (default), acp, utf-8, ucs-2/utf-16, ucs-2le/utf-16le, ucs-2be/utf-16be, ucs-4/utf-32, ucs-4le/utf-32le, ucs-4be/utf-32be; dashless forms (utf8, ucs2, ucs2le, …​) are also accepted

preallocated

Set to true for pre-allocated log files (padding with NUL characters)

detectBrokenPrealloc

Detect broken pre-allocation (partial NUL padding)

snapshot

Use VSS snapshots for reading (Windows only)

keepOpen

Keep file handle open between reads (default: true)

ignoreModificationTime

Ignore file modification time for change detection

rescan

Rescan file from beginning on each check cycle

followSymlinks

Follow symbolic links to target files

removeEscapeSequences

Strip ANSI escape sequences from log lines

File Path Macros

The <file> element path supports macro expansion:

  • Environment variables: ${ENV_VAR_NAME} — e.g., ${LOGDIR}/app.log

  • strftime format codes: %Y, %m, %d, %a, etc. — e.g., C:\Windows\system32\dhcp\DhcpSrvLog-%a.log (day-of-week rotation)

  • Shell command output: text enclosed in backticks is executed and replaced with stdout — e.g., `hostname`.log

Parser Elements Summary

Element Description

<file>

Path to the log file to monitor (supports strftime codes, environment variables, and backtick command expansion — see File Path Macros above)

<rules>

Container for rule definitions

<rule>

Individual matching rule

<match>

Regular expression pattern to match against log lines

<event>

Event to generate when the rule matches (numeric code or event name)

<severity> / <level>

Match condition on the incoming record’s log level (extended mode only)

<id> / <facility>

Match condition on the incoming record’s event ID or facility (extended mode only)

<source> / <tag>

Match condition on the incoming record’s source or tag (extended mode only)

<logName>

Match condition on the log name or syslog source address (extended mode only, server side)

<description>

Rule label shown in trace output

<context>

Activate or clear a context for multi-line matching

<metrics> / <metric>

Expose values captured from log lines as agent metrics

<push>

Legacy form of <metric> with push delivery

<agentAction>

Execute an agent action when the rule matches

<macros> / <macro>

Container for reusable regex macro definitions / individual macro

<exclusionSchedules> / <schedule>

Container for time-based exclusion schedules / individual cron schedule

Rule Element

The <rule> element accepts these attributes:

Attribute Default Description

context

Only activate this rule when the named context is active

name

Rule name (used to restore per-rule check and match counters when the parser configuration is reloaded)

guid

(auto-generated)

Rule GUID; generated automatically if not specified

break

false

Force-stop rule processing after this rule matches, even if processAll=true

doNotSaveToDatabase

false

Do not save matched records to the database (used with syslog parser)

Match Element

The <match> element uses PCRE (Perl-Compatible Regular Expressions) and supports these attributes:

Attribute Default Description

ignoreCase

true

Case-insensitive regex matching

invert

false

Match lines that do NOT match the pattern

repeatCount

0

Number of matches required before generating event (0 = immediate)

repeatInterval

0

Time window in seconds for counting repeats

reset

true

Reset repeat counter when threshold is reached

absence

false

Turn the rule into an absence rule: it fires when no matching record arrives within absenceInterval

absenceInterval

0

Time in seconds without a matching record after which an absence rule fires

absenceRealertInterval

0

Interval in seconds between repeated alerts while the absence condition persists

Both repeatCount and repeatInterval must be greater than 0 to enable repeat checking.

Named Event Parameters

PCRE named capture groups in the match pattern become named parameters of the generated event:

<match>user (?&lt;username&gt;\S+) logged in from (?&lt;ipaddr&gt;\S+)</match>

The captured values can then be referenced in EPP rules, alarms, and notifications as %<username> and %<ipaddr>. Unnamed capture groups are automatically named group_1, group_2, and so on, and reach the event as named parameters — reference them as %<group_1>, %<group_2>, etc. (there is no positional parameter list). When editing the XML directly, < and > must be escaped as < and > (the management client editor does this automatically).

Context Element

The <context> element controls multi-line matching. The context name is the element text (used in the context attribute of other rules):

<context action="set" reset="auto">STARTUP</context>
Attribute Description

action

set to activate the context, clear to deactivate it

reset

Context reset mode, only valid with action="set": auto (default) — the context is cleared automatically as soon as a rule that requires it matches; manual — the context stays active until cleared by a rule with action="clear"

Event Element

The <event> element defines the event to generate when the rule matches. The element content is either a numeric event code or an event name:

<event tag="ssh">MY_CUSTOM_EVENT</event>

The optional tag attribute sets the tag of the generated event.

Severity Element

The <severity> element is a rule match condition on the incoming record’s log level, evaluated only in extended mode (syslog, Windows Event Log, and OpenTelemetry log parsing). <level> is an exact alias for <severity>. The value is a bitmask where each log level contributes bit 2^severity; the rule matches only if the bit corresponding to the record’s level is set. It does not set the severity of the generated event.

Id and Facility Elements

<id> and <facility> are aliases for the same rule match condition, evaluated only in extended mode. The element text is a single number or a range in the form start - end, matched against the record’s event ID (Windows Event Log) or facility (syslog).

Source and Tag Elements

<source> and <tag> are aliases for the same rule match condition, evaluated only in extended mode. The element text is a case-insensitive glob pattern matched against the record’s source (Windows Event Log) or tag (syslog).

Description Element

The <description> element is a rule label shown in trace output for troubleshooting. It has no effect on the generated event.

Metric Element

The <metrics> element extracts values from log lines and exposes them as agent metrics:

<metrics>
  <metric group="1">metric.name</metric>
</metrics>

  • group (default: 1) — which regex capture group’s value to use as the metric value

  • push (default: false) — push the value via data push instead of making it a queryable metric

A legacy <push> element is also supported: <push group="1">metric.name</push>.

Agent Action Element

The <agentAction> element triggers an agent action when a rule matches:

<agentAction action="action_name">arguments</agentAction>

The action attribute specifies the agent action name to invoke. The element text is split on whitespace into an argument list (quoting is not supported); the arguments are passed to the agent action, where they can be referenced as $1 through $9 in the action’s command line.

Log Name Filter Element

The <logName> element is a rule match condition evaluated only in extended mode, on the server side:

<logName>*Security*</logName>

The value is a wildcard pattern matched against:

  • the event channel name, for the agent-side Windows event log parser (scopes the rule to specific channels when the parser monitors several);

  • the log name, for the server-side Windows event log parser (events forwarded by agents);

  • the source IP address of the message, for the server-side syslog parser (the same record field carries the source address there).

It is never evaluated for file parsers.

Exclusion Schedule Element

The <exclusionSchedules> element suspends log parsing during specific time periods:

<exclusionSchedules>
  <schedule>* 2-4 * * *</schedule>
</exclusionSchedules>

The <schedule> element uses cron format.

Macros Element

The <macros> element defines reusable regex patterns:

<macros>
  <macro name="IP">(?:\d{1,3}\.){3}\d{1,3}</macro>
</macros>

Macros are referenced with @{MACRO_NAME} syntax in match patterns. Use \@ to include a literal @ character.

Log Parser Provided Metrics

The Log Watch subagent provides metrics about monitored log files:

Metric Description

LogWatch.Parser.MatchedRecords(parser)

Number of records matched by the parser

LogWatch.Parser.ProcessedRecords(parser)

Total records processed by the parser

LogWatch.Parser.Status(parser)

Parser status

LogWatch.Parser.MetricValue(parser,file,metric)

Current value of a metric defined in a <metrics> element

LogWatch.Parser.MetricTimestamp(parser,file,metric)

Timestamp of the last update of a metric defined in a <metrics> element

LogWatch.MetricValue(metric)

Current value of a metric defined in a <metrics> element, identified by metric name only

LogWatch.MetricTimestamp(metric)

Timestamp of the last update of a metric defined in a <metrics> element, identified by metric name only

The MatchedRecords, ProcessedRecords, and Status metrics accept an optional second argument with the monitored file name, e.g., LogWatch.Parser.Status(syslog,/var/log/messages).

Available lists:

List Description

LogWatch.Parsers

Names of all defined parsers

LogWatch.Metrics

Names of all metrics defined in parsers

Available tables:

Table Instance column Description

LogWatch.Metrics

NAME

All metrics defined in parsers with their current values