---
title: "Parsing key=value pairs"
url: "https://axoflow.com/docs/axosyslog-core/4.28/chapter-parsers/key-value-parser/"
last_modified: "2026-07-29T13:15:11+02:00"
---

> For the complete documentation index, see [llms.txt](https://axoflow.com/docs/axosyslog-core/4.28/llms.txt).

# Parsing key=value pairs

The AxoSyslog application can separate a message consisting of whitespace or comma-separated `key=value` pairs (for example, Postfix log messages) into name-value pairs. You can also specify other separator character instead of the equal sign, for example, colon (`:`) to parse MySQL log messages. The AxoSyslog application automatically trims any leading or trailing whitespace characters from the keys and values, and also parses values that contain unquoted whitespace. For details on using value-pairs in AxoSyslog see [Structuring macros, metadata, and other value-pairs](https://axoflow.com/docs/axosyslog-core/4.28/chapter-concepts/concepts-value-pairs/index.md).

You can refer to the separated parts of the message using the key of the value as a macro. For example, if the message contains `KEY1=value1,KEY2=value2`, you can refer to the values as `${KEY1}` and `${KEY2}`.

See also the equivalent FilterX function, [`parse_kv()`](https://axoflow.com/docs/axosyslog-core/4.28/filterx/function-reference/index.md#parse-kv).

> **Note:**
> If a log message contains the same key multiple times (for example, `key1=value1, key2=value2, key1=value3, key3=value4, key1=value5`), then AxoSyslog only stores the last (rightmost) value for the key. Using the previous example, AxoSyslog will store the following pairs: `key1=value5, key2=value2, key3=value4`.

> **Warning:**
>
> If the names of keys in the message is the same as the names of AxoSyslog soft macros, the value from the parsed message will overwrite the value of the macro. For example, the `PROGRAM=value1, MESSAGE=value2` content will overwrite the `${PROGRAM}` and `${MESSAGE}` macros. To avoid overwriting such macros, use the `prefix()` option.
>
> Hard macros cannot be modified, so they will not be overwritten. For details on the macro types, see [Hard versus soft macros](https://axoflow.com/docs/axosyslog-core/4.28/chapter-manipulating-messages/customizing-message-format/macros-hard-vs-soft/index.md).
>
> The parser discards message sections that are not `key=value` pairs, even if they appear between `key=value` pairs that can be parsed.
>
> The names of the keys can contain only the following characters: numbers (0-9), letters (a-z,A-Z), underscore (_), dot (.), hyphen (-). Other special characters are not permitted.

To parse `key=value` pairs, define a parser that has the `kv-parser()` option. Defining the prefix is optional. By default, the parser will process the `${MESSAGE}` part of the log message. You can also define the parser inline in the log path.

## Declaration:

```shell
   parser parser_name {
        kv-parser(
            prefix()
        );
    };
```

## Example: Using a key=value parser

In the following example, the source is a log message consisting of comma-separated `key=value` pairs, for example, a Postfix log message:

```shell
   Jun 20 12:05:12 mail.example.com <info> postfix/qmgr[35789]: EC2AC1947DA: from=<me@example.com>, size=807, nrcpt=1 (queue active)
```

The kv-parser inserts the “`.kv.`” prefix before all extracted name-value pairs. The destination is a file, that uses the `format-json` template function. Every name-value pair that begins with a dot ("`.`") character will be written to the file (`dot-nv-pairs`). The log line connects the source, the destination and the parser.

```shell
   source s_kv {
        network(port(21514));
    };

    destination d_json {
        file("/tmp/test.json"
            template("$(format-json --scope dot-nv-pairs)\n"));
    };

    parser p_kv {
        kv-parser (prefix(".kv."));
    };

    log {
        source(s_kv);
        parser(p_kv);
        destination(d_json);
    };
```

You can also define the parser inline in the log path.

```shell
   source s_kv {
        network(port(21514));
    };

    destination d_json {
        file("/tmp/test.json"
            template("$(format-json --scope dot-nv-pairs)\n"));
    };

    log {
        source(s_kv);
        parser {
            kv-parser (prefix(".kv."));
        };
        destination(d_json);
    };
```

You can set the separator character between the key and the value to parse for example, `key:value` pairs, like MySQL logs:

```shell
   Mar  7 12:39:25 myhost MysqlClient[20824]: SYSTEM_USER:'oscar', MYSQL_USER:'my_oscar', CONNECTION_ID:23, DB_SERVER:'127.0.0.1', DB:'--', QUERY:'USE test;'
```

```shell
   parser p_mysql {
        kv-parser(value-separator(":") prefix(".mysql."));
    };
```

---

[Options of key=value parsers](https://axoflow.com/docs/axosyslog-core/4.28/chapter-parsers/key-value-parser/kv-parser-options/index.md)

Last modified July 29, 2026: [Link classic rewrite rules and parsers to their FilterX counterparts (e9be5c49)](https://github.com/axoflow/axosyslog-core-docs/commit/e9be5c49098f40c3137bf588a8a7453ca2b061de)