JSON Dotted Key Rewriter (mmjsonrewrite)¶

Module Name:	mmjsonrewrite
Author:	rsyslog project
Available since:	8.2410.0

Warning

mmjsonrewrite is experimental. Parameter names and behavior may change without notice while the interface stabilizes. Expect breaking changes in future releases.

Purpose¶

mmjsonrewrite scans a JSON object for property names that contain dot characters and rewrites those entries into nested objects. This mirrors the hierarchy that list templates create when option.jsonfTree is enabled, making it easier to normalize dotted payloads before forwarding them to downstream processors.

Failure conditions¶

mmjsonrewrite aborts the action in the following situations:

The input property does not resolve to a JSON object.
The destination property already exists on the message.
Rewriting a dotted path would overwrite an existing incompatible value.

Configuration Parameters¶

Note

Parameter names are case-insensitive. CamelCase is recommended for readability.

Action Parameters¶

Parameter	Summary
input	Names the JSON property that supplies the tree to rewrite.
output	Sets the destination property that receives the rewritten JSON tree.

Conflict handling¶

When dotted paths collide with an existing scalar or incompatible container, mmjsonrewrite stops processing, leaves the output unset, and logs an error that includes the offending path. Review the reported path to adjust the upstream payload or choose a different destination.

Examples¶

Normalize dotted JSON properties¶

The following snippet converts dotted keys inside $!raw into nested objects stored under $!structured:

module(load="mmjsonrewrite")
module(load="imtcp")

input(type="imtcp" port="10514" ruleset="rewrite-json")

ruleset(name="rewrite-json") {
    action(type="mmjsonrewrite" input="$!raw" output="$!structured")
    action(type="omfile" file="/tmp/out.json"
           template="structured-json")
}

template(name="structured-json" type="string"
         string="%$!structured%\n")

Troubleshooting¶

Conflicts usually stem from payloads that mix dotted keys with non-object values at the same hierarchy. Inspect the logged path, rename the conflicting key, or preprocess the message before running mmjsonrewrite.

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project