Adding upstream version 8.2402.0+dfsg.upstream/8.2402.0+dfsg

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 43 insertions, 0 deletions

diff --git a/source/configuration/modules/idx_stringgen.rst b/source/configuration/modules/idx_stringgen.rst
new file mode 100644
index 0000000..221f0d4
--- /dev/null
+++ b/source/configuration/modules/idx_stringgen.rst
@@ -0,0 +1,43 @@
+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 with 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).
+