Use this documentation with care! It describes
the heavily outdated version 5, which was actively
developed around 2010 and is considered dead by the
rsyslog team for many years now.
This documentation reflects the latest update of the
previously existing (now removed) v5-stable branch.
It describes the 5.10.2 version, which was never
released. As such, it contains some content that
does not apply to any released version.
To obtain the doc that properly matches your installed
v5 version, obtain the doc set from your distro. Each
version of rsyslog contained the version that exactly
matches it.
As general advise, it is strongly suggested to
upgrade to the current version supported by the rsyslog
project. The current version can always be found on
the right-hand side info box on the
rsyslog web site.
Note that there is no rsyslog community support available
for this heavily outdated version. If you need to stick
with it, please ask your distribution for support.
String Generator Modules¶
String generator modules are used, as the name implies, to generate strings based on the message content. They are currently tightly coupled with the template system. Their primary use is to speed up template processing by providing a native C interface to template generation. These modules exist since 5.5.6. To get an idea of the potential speedup, the default file format, when generated by a string generator, provides a roughly 5% speedup. For more complex strings, especially those that include multiple regular expressions, the speedup may be considerably higher.
String generator modules are written to a quite simple interface. However, a word of caution is due: they access the rsyslog message object via a low-level interface. That interface is not guaranteed yet to stay stable. So it may be necessary to modify string generator modules if the interface changes. Obviously, we will not do that without good reason, but it may happen.
Rsyslog comes with a set of core, build-in string generators, which are used to provide those default templates that we consider to be time-critical:
- smfile - the default rsyslog file format
- smfwd - the default rsyslog (network) forwarding format
- smtradfile - the traditional syslog file format
- smfwd - the traditional syslog (network) forwarding format
Note that when you replace these defaults be some custom strings, you will loose some performance (around 5%). For typical systems, this is not really relevant. But for a high-performance systems, it may be very relevant. To solve that issue, create a new string generator module for your custom format, starting out from one of the default generators provided. If you can not do this yourself, you may want to contact Adiscon as we offer custom development of string generators at a very low price.
Note that string generator modules can be dynamically loaded. However, the default ones provided are so important that they are build right into the executable. But this does not need to be done that way (and it is straightforward to do it dynamic).