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")

bracketing¶

Description¶

Module usage¶

See also¶