Matches

Flow Control

Synopsis

Tests whether a field value contains a text pattern or matches a regular expression, then routes execution to on_success or on_failure processor chains based on the result.

Schema

- matches:
    field: <ident>
    text: <string>
    value_field: <ident>
    mode: <string>
    case_sensitive: <boolean>
    description: <text>
    disabled: <boolean>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>

Configuration

Field	Required	Default	Description
field	Y		Field to test; must contain a string, []string, or []interface{} value
text	Y*		Literal text or template pattern to match against
value_field	Y*		Field whose string value is used as the match pattern
mode	N	contains	Match mode: contains (substring) or regex (regular expression)
case_sensitive	N	false	When true, substring matching is case-sensitive; has no effect in regex mode
description	N		Explanatory note
disabled	N	false	When true, processor is skipped
if	N		Condition to activate processor
ignore_failure	N	false	See Handling Failures
ignore_missing	N	false	When true and field does not exist, exit quietly
on_failure	N		See Handling Failures
on_success	N		See Handling Success
tag	N		Identifier

* = Either text or value_field must be specified, but not both.

Details

The processor resolves the match pattern first, then retrieves the value of field. If field holds a plain string, that string is tested. If field holds an array ([]string or []interface{}), the processor tests each element and succeeds as soon as any element matches.

Contains mode (default) uses strings.Contains with optional case folding. When case_sensitive is false (the default), both the field value and the pattern are lowercased before comparison. Setting case_sensitive: true requires an exact case match.

Regex mode compiles and caches the pattern. The cache avoids recompilation on repeated invocations. An invalid regex pattern produces an error rather than a no-match result.

The text field supports template syntax ({{{field_name}}}), allowing the pattern to be constructed dynamically from other fields in the log entry. value_field reads the pattern from another field directly, without template processing.

When a match is found, on_success processors run. When no match is found (ErrNoMatch), on_failure processors run without an error being recorded. When the processor itself fails (missing field, invalid regex, type error), the standard ignore_failure and ignore_missing rules apply, and on_failure processors run with the error.

The processor only accepts string-typed field values. A numeric field such as response_code: 404 produces a type error even if the pattern is "404". Convert numeric fields before using this processor.

note

To test a field value against a list of candidates rather than a single pattern, see Contains.

Examples

Substring Match

Checking if a user agent string contains a known platform identifier...	{ "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" } - matches: field: user_agent text: "Windows NT" on_success: - set: field: platform value: windows
Match succeeds (case-insensitive by default), on_success processors run...	{ "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36", "platform": "windows" }

Regex Match

Testing a source IP against a private network prefix using a regular expression...	{ "src_ip": "192.168.1.45" } - matches: field: src_ip text: "^192\\.168\\." mode: regex on_success: - set: field: network_zone value: internal on_failure: - set: field: network_zone value: external
IP matches the RFC 1918 prefix; on_success sets the zone...	{ "src_ip": "192.168.1.45", "network_zone": "internal" }

Array Field

Checking whether any tag in a string array contains a target value...	{ "tags": ["env:production", "region:us-east-1", "service:api-gateway"] } - matches: field: tags text: "env:production" on_success: - set: field: is_production value: "true"
Processor iterates all array elements and succeeds on the first match...	{ "tags": ["env:production", "region:us-east-1", "service:api-gateway"], "is_production": "true" }

Dynamic Pattern via value_field

Using a field value as the match pattern to compare two runtime values...	{ "request_path": "/api/v1/users/me", "allowed_path": "/api/v1/users" } - matches: field: request_path value_field: allowed_path on_failure: - set: field: access value: denied
request_path contains allowed_path as a substring; no failure occurs...	{ "request_path": "/api/v1/users/me", "allowed_path": "/api/v1/users" }

Template Pattern

Building the match pattern from another field using template syntax...	{ "request_path": "/api/v1/orgs/42/members", "org_id": "42" } - matches: field: request_path text: "/orgs/{{{org_id}}}/" on_success: - set: field: matched_org value: "{{{org_id}}}"
Template resolves to /orgs/42/ before matching; path contains that substring...	{ "request_path": "/api/v1/orgs/42/members", "org_id": "42", "matched_org": "42" }

Missing Field Handling

Suppressing the error when the target field is absent...	{ "src_ip": "192.168.1.1" } - matches: field: user_agent text: "Mozilla" ignore_missing: true
user_agent does not exist; processor exits quietly without error or modification...	{ "src_ip": "192.168.1.1" }