# bracketing

Adds BEGIN and END marker messages so post-processing can group statistics blocks.

This parameter applies to impstats: Generate Periodic Statistics of Internal Counters.

Name:

  bracketing

Scope:

  module

Type:

  boolean

Default:

  module=off

Required?:

  no

Introduced:

  8.4.1

## Description

Added in version 8.4.1.

This is a utility setting for folks who post-process impstats logs and would like to know the begin and end of a block of statistics. When `bracketing` is set to `on`, impstats issues a `BEGIN` message before the first counter is issued, then all counter values are issued, and then an `END` message follows. As such, if and only if messages are kept in sequence, a block of stats counts can easily be identified by those BEGIN and END messages.

Note well: in general, sequence of syslog messages is not strict and is not ordered in sequence of message generation. There are various occasions that can cause message reordering, some examples are:

- using multiple threads

- using UDP forwarding

- using relay systems, especially with buffering enabled

- using disk-assisted queues

This is not a problem with rsyslog, but rather the way a concurrent world works. For strict order, a specific order predicate (e.g. a sufficiently fine-grained timestamp) must be used.

As such, BEGIN and END records may actually indicate the begin and end of a block of statistics - or they may not. Any order is possible in theory. So the bracketing option does not in all cases work as expected. This is the reason why it is turned off by default.

However, bracketing may still be useful for many use cases. First and foremost, while there are many scenarios in which messages become reordered, in practice it happens relatively seldom. So most of the time the statistics records will come in as expected and actually will be bracketed by the BEGIN and END messages. Consequently, if an application can handle occasional out-of-order delivery (e.g. by graceful degradation), bracketing may actually be a great solution. It is, however, very important to know and handle out of order delivery. For most real-world deployments, a good way to handle it is to ignore unexpected records and use the previous values for ones missing in the current block. To guard against two or more blocks being mixed, it may also be a good idea to never reset a value to a lower bound, except when that lower bound is seen consistently (which happens due to a restart). Note that such lower bound logic requires resetcounters (`resetCounters` in camelCase examples) to be set to `off`.

## Module usage

    module(load="impstats" bracketing="on")

## See also

See also impstats: Generate Periodic Statistics of Internal Counters.

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.