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 <mailto:info%40adiscon.com>`_ 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).

