KV

Parse Elastic Compatible

Synopsis

Parses strings to extract key-value pairs into structured fields.

Schema

- kv:
    field: <ident>
    field_split: <regex>
    value_split: <regex>
    description: <text>
    exclude_keys: <string[]>
    if: <script>
    ignore_casting: <boolean>
    ignore_failure: <boolean>
    ignore_missing: <boolean>
    include_keys: <string[]>
    lowercase_keys: <boolean>
    on_failure: <processor[]>
    on_success: <processor[]>
    prefix: <string>
    strip_brackets: <boolean>
    tag: <string>
    target_field: <ident>
    trim_key: <char[]>
    trim_value: <char[]>

Configuration

The following fields are used to define the processor:

Field	Required	Default	Description
field	Y	-	Source field containing key-value pairs
field_split	Y	-	Delimiter between key-value pairs
value_split	Y	-	Delimiter between keys and values
description	N	-	Documentation note
exclude_keys	N	-	Keys to exclude from output
if	N	-	Conditional expression
ignore_casting	N	false	Disable automatic type conversion
ignore_failure	N	false	Skip processing errors
ignore_missing	N	false	Skip if input field missing
include_keys	N	-	Only include specified keys
lowercase_keys	N	false	Convert all keys to lowercase
on_failure	N	-	Error handling processors
on_success	N	-	Success handling processors
prefix	N	-	Prefix for extracted keys
strip_brackets	N	false	Remove brackets from values
tag	N	-	Identifier for logging
target_field	N	-	Output field for parsed data
trim_key	N	-	Characters to trim from keys
trim_value	N	-	Characters to trim from values

Details

The processor supports various delimiter patterns, key filtering, value formatting, and automatic type casting.

note

Whitespace around field and value delimiters is automatically trimmed.

warning

Malformed inputs may result in missing entries or incomplete parsing.

Examples

Basic

Parsing semicolon-separated pairs...	{ "message": "key1=value1;key2=value2;key3=value3" } - kv: field: message field_split: ";" value_split: "="
extracts the structured fields:	{ "message": "key1=value1;key2=value2;key3=value3", "key1": "value1", "key2": "value2", "key3": "value3" }

Keep Original

Storing the parsed values in a separate object...	{ "data": "host=localhost:8080, status=200, method=GET" } - kv: field: data field_split: "," value_split: "=" target_field: request_info
groups related fields:	{ "data": "host=localhost:8080, status=200, method=GET", "request_info": { "host": "localhost:8080", "status": "200", "method": "GET" } }

Keys

Including only specific keys...	{ "log": "user=admin role=sudo group=wheel status=active" } - kv: field: log field_split: " " value_split: "=" include_keys: ["user", "role"]
extracts only those records:	{ "log": "user=admin role=sudo group=wheel status=active", "user": "admin", "role": "sudo" }

Formatting

Cleaning up and formatting values...	{ "data": "name=[John], age='25', city=<New York>" } - kv: field: data field_split: "," value_split: "=" strip_brackets: true trim_value: "'" lowercase_keys: true
standardizes the output:	{ "data": "name=[John], age='25', city=<New York>", "name": "John", "age": "25", "city": "New York" }

Prefixing

Adding a prefix to the extracted keys...	{ "metrics": "cpu=80,mem=60,disk=45" } - kv: field: metrics field_split: "," value_split: "=" prefix: "system_"
places the fields in a namespace:	{ "metrics": "cpu=80,mem=60,disk=45", "system_cpu": "80", "system_mem": "60", "system_disk": "45" }