Subtree template type¶

Builds output from a full JSON subtree (CEE). Best used when the schema has already been remapped and an appropriate variable tree exists.

Name:: type="subtree"
Scope:: template
Type:: subtree
Introduced:: 7.1.4

Description¶

The subtree template type generates output from a complete (CEE/JSON) subtree. This is useful when working with data pipelines where schema mapping is done beforehand and a full variable tree (e.g. $!ecs) is available.

This method is required when an entire subtree must be placed at the root of the generated object. With other template types, only sub-containers can be produced. Constant text cannot be inserted inside subtree templates.

Subtree templates are often used with structured outputs such as ommongodb, omelasticsearch, or with text-based outputs like omfile.

They are particularly effective after message transformation with parsing modules such as mmjsonparse, mmaudit, or mmleefparse.

Example: ECS mapping¶

A typical workflow is to normalize message content into an ECS-compatible subtree and then export it with a subtree template:

set $!ecs!event!original = $msg;
set $!ecs!host!hostname = $hostname;
set $!ecs!log!level = $syslogseverity-text;
set $!ecs!observer!type = "rsyslog";
template(name="ecs_tpl" type="subtree" subtree="$!ecs")

Here the message is mapped into ECS fields under $!ecs. The complete ECS subtree is then emitted as JSON by the template.

Data pipeline usage¶

Subtree templates are a natural part of rsyslog data pipelines:

        flowchart TD
   A["Input<br>(imudp, imtcp, imkafka)"]
   B["Parser<br>(mmjsonparse, mmaudit, ...)"]
   C["Schema Tree<br>($!ecs)"]
   D["Template<br>type=subtree"]
   E["Action<br>(omfile, omkafka, ...)"]

   A --> B --> C --> D --> E

Alternative mapping approach¶

If you do not yet have a remapped schema tree, consider using a list template instead. List templates allow mapping fields one-by-one into structured output before exporting.

Notes¶

Use subtree templates when a full schema tree is already present.
Use list templates when building or remapping the schema incrementally.