Index Of

Search

Synopsis

Writes the character position of a substring within a string field into a target field. The position is 0-based, and -1 means the substring was not found.

Schema

- index_of:
    field: <ident>
    substring: <string>
    regex: <boolean>
    occurrence: <numeric>
    description: <text>
    if: <script>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    tag: <string>
    target_field: <ident>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Field containing the string to search
substring	Y	-	Text to search for. Supports templates, so it can be built from another field
regex	N	false	Treat substring as a regular expression instead of literal text
occurrence	N	1	Which match to report, counting from 1. A negative value writes null
description	N	-	Explanatory note
if	N	-	Condition to run
ignore_failure	N	false	See Handling Failures
ignore_missing	N	false	If true, quietly exit if field doesn't exist
on_failure	N	-	See Handling Failures
on_success	N	-	See Handling Success
tag	N	-	Identifier
disabled	N	false	When true, the processor is skipped and the event continues to the next one. Lets you take a processor out of the path without removing its configuration
target_field	N	field	Field to store the position. Defaults to field, replacing the string that was searched

Details

The position counts characters, not bytes, so a match after a multi-byte character reports the position a reader would count rather than the storage offset.

Three results are possible, and they are distinct:

Result	Meaning
0 or greater	The character position of the match
-1	Searched, and the substring is not present
null	Not searched, because occurrence was negative

Plain-text matching scans forward without overlap: after a match, the search resumes past the end of it. Searching "aaaa" for "aa" finds occurrence 1 at position 0 and occurrence 2 at position 2, not position 1.

An empty substring reports position 0, matching the behavior of the underlying string search rather than being treated as an error.

Under regex, the substring is compiled as a pattern and occurrence selects among the matches it finds. occurrence: 0 is treated as 1, so the first match is the default in both modes.

note

target_field defaults to field, which replaces the string you searched with a number. Set it explicitly whenever the original is still needed.

Examples

Finding a Delimiter

Locating the separator in a qualified name...	{ "principal": "DOMAIN\\jsmith" } - index_of: field: principal substring: "\\" target_field: separator_at
gives the position to split on:	{ "principal": "DOMAIN\\jsmith", "separator_at": 6 }

Absent Substring

A substring that is not present reports -1 rather than failing...	{ "message": "connection established" } - index_of: field: message substring: "error" target_field: error_at
so the result can be tested downstream:	{ "message": "connection established", "error_at": -1 }

Selecting a Later Occurrence

Reporting the second match instead of the first...	{ "path": "/var/log/app/error.log" } - index_of: field: path substring: "/" occurrence: 2 target_field: second_slash
counting matches from 1:	{ "path": "/var/log/app/error.log", "second_slash": 4 }

Regular Expression Search

With regex, the substring is a pattern...	{ "line": "status=200 latency=45ms" } - index_of: field: line substring: "[0-9]+ms" regex: true target_field: latency_at
reporting where the match begins:	{ "line": "status=200 latency=45ms", "latency_at": 19 }