# 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.

## See also

- List template type

- Templates

- ommongodb: MongoDB Output Module

- omelasticsearch: Elasticsearch Output Module

- omfile: File Output Module

- omkafka: write to Apache Kafka

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

Contributing: Source & docs: rsyslog source project

© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.