Key-value parse events. This function can run an extra key-value parser on events. It is used to parse key-values of the form:

  • key=value

  • key="value"

  • key='value'

  • key = value

Both key and value can be either quoted using " or ', or unquoted.

For a log line like this:

ini
2017-02-22T13:14:01.917+0000 [main thread] INFO UserService - creating new user id=123, name='john doe' email=john@doe

The key-value parser extracts the fields:

  • id=123

  • name='john doe'

  • email=john@doe

Use the parameter field to specify which fields should be key-value parsed. Specifying @rawstring to key-value parse the rawstring.

Function Traits: Transformation

ParameterTypeRequiredDefaultDescription
asstringoptional  Prefix for all resolved field keys.
excludeEmptybooleanoptional  If the value of a key is empty, exclude the field.
field[a]Array of stringsoptional@rawstring Fields that should be key-value parsed.
overridebooleanoptional  Override existing values for keys that already exist in the event.
separatorstringoptional  The token that separates the key from the value — a single char only.
separatorPaddingstringoptionalunknown Help the function recognize unquoted empty values and parse them by specifying whether there is a whitespace around the key-value separator (typically =).

[a] The argument name field can be omitted.

The parameter name for field can be omitted; the following forms are equivalent:

logscale
kvParse("@rawstring")

and:

logscale
kvParse(field="@rawstring")

kvParse() Examples

  • Key-value parse the log line:

ini
creating new user id=123, name='john doe' email=john@doe.

This will add the fields id=123, name='john doe' and email=john@doe to the event:

logscale
kvParse()

  • Key-value parse the log line:

ini
creating new user id=123, name='john doe' email=john@doe loglevel=ERROR.

Assuming the event already has a loglevel field, replacing the value of that field with ERROR requires the override=true parameter:

logscale
kvParse(override=true)

  • Key-value parse a nested field. In this example we will use JSON input:

json
{
  "service": "paymentService",
  "type": "payment",
  "metadata": "host=server5,transactionID=123,processingTime=100"
}

and parse out the key-values in the metadata field:

logscale
parseJSON()
| kvParse(metadata)

  • Key-value parse the log line and export fields with a prefix:

ini
creating new user id=123, name='john doe' email=john@doe.

This will add the fields user.id=123, user.name='john doe' and user.email=john@doe to the event:

logscale
kvParse(as="user")

  • Key-value parse the log line:

ini
firstname = John middlename = lastname = Doe

This will add the fields firstname=John, middleName= (empty value) and lastname=Doe to the event:

logscale
kvParse(separatorPadding="yes")