mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-12 19:30:42 +01:00
Codex/refactor rsyslog module parameter documentation p47sz4 (#6285)
* omsendertrack: split parameter docs into reference pages - replace inline parameter tables with summary list-table includes and add hidden toctree - create per-parameter reference pages with preserved descriptions and usage examples - update internal references to new scoped anchors for senderid, statefile, interval, and cmdfile With the help of AI-Agent: ChatGPT
This commit is contained in:
Ulrike Gerhards
GitHub
parent
87235853a6
commit
27d488b05f
@ -35,7 +35,7 @@ Key uses for ``omsendertrack`` include:
|
||||
daemon restarts, ensuring continuous tracking.
|
||||
|
||||
The module achieves this by periodically writing these statistics to a JSON
|
||||
:ref:`statefile <omsendertrack_statefile>`.
|
||||
:ref:`statefile <param-omsendertrack-statefile>`.
|
||||
|
||||
Functionality
|
||||
-------------
|
||||
@ -48,7 +48,7 @@ Initialization
|
||||
|
||||
Upon rsyslog startup, the ``omsendertrack`` module attempts to load its
|
||||
previously saved state from the configured :ref:`statefile
|
||||
<omsendertrack_statefile>`. This data, which includes sender identifiers,
|
||||
<param-omsendertrack-statefile>`. This data, which includes sender identifiers,
|
||||
message counts, and last event times, is loaded into an in-memory hash table.
|
||||
This ensures that message statistics are restored and tracking continues
|
||||
seamlessly across daemon restarts. A background task is then spawned to handle
|
||||
@ -60,7 +60,7 @@ OnAction Call (Message Processing)
|
||||
When a message is routed to an ``omsendertrack`` action:
|
||||
|
||||
1. **Sender Identification:** The module uses the configured :ref:`senderid
|
||||
<omsendertrack_senderid>` template to derive a unique identifier for the
|
||||
<param-omsendertrack-senderid>` template to derive a unique identifier for the
|
||||
message sender.
|
||||
2. **Statistic Update:** It then updates or inserts an entry for this sender in
|
||||
its internal hash table.
|
||||
@ -75,7 +75,7 @@ HUP Signal Handling
|
||||
|
||||
When rsyslog receives a HUP signal (typically used for configuration reloads),
|
||||
the ``omsendertrack`` module is designed to check for the existence of a
|
||||
:ref:`cmdfile <omsendertrack_cmdfile>`. If a `cmdfile` is specified and found,
|
||||
:ref:`cmdfile <param-omsendertrack-cmdfile>`. If a `cmdfile` is specified and found,
|
||||
it would be read and its commands processed. After processing, the `cmdfile`
|
||||
would be deleted to prevent re-execution on subsequent HUP signals.
|
||||
|
||||
@ -86,7 +86,7 @@ Background Task
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
A dedicated background task is responsible for persisting the module's current
|
||||
state to the configured :ref:`statefile <omsendertrack_statefile>`. This task
|
||||
state to the configured :ref:`statefile <param-omsendertrack-statefile>`. This task
|
||||
wakes up at the `interval` specified in the configuration. It performs atomic
|
||||
writes to the `statefile` to prevent data corruption, even if rsyslog
|
||||
unexpectedly terminates during a write operation.
|
||||
@ -96,7 +96,7 @@ Shutdown
|
||||
|
||||
During rsyslog shutdown, the ``omsendertrack`` module ensures that the most
|
||||
current sender statistics are saved to the :ref:`statefile
|
||||
<omsendertrack_statefile>`. This critical step guarantees data persistence and
|
||||
<param-omsendertrack-statefile>`. This critical step guarantees data persistence and
|
||||
allows for an accurate resumption of tracking when rsyslog restarts.
|
||||
|
||||
Configuration
|
||||
@ -106,101 +106,41 @@ The ``omsendertrack`` module supports the following action parameters.
|
||||
|
||||
.. note::
|
||||
|
||||
Parameter names are case-insensitive.
|
||||
Parameter names are case-insensitive; camelCase is recommended for readability.
|
||||
|
||||
Action Parameters
|
||||
-----------------
|
||||
|
||||
senderid
|
||||
^^^^^^^^
|
||||
.. list-table::
|
||||
:widths: 30 70
|
||||
:header-rows: 1
|
||||
|
||||
.. _omsendertrack_senderid:
|
||||
* - Parameter
|
||||
- Summary
|
||||
* - :ref:`param-omsendertrack-senderid`
|
||||
- .. include:: ../../reference/parameters/omsendertrack-senderid.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omsendertrack-interval`
|
||||
- .. include:: ../../reference/parameters/omsendertrack-interval.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omsendertrack-statefile`
|
||||
- .. include:: ../../reference/parameters/omsendertrack-statefile.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
* - :ref:`param-omsendertrack-cmdfile`
|
||||
- .. include:: ../../reference/parameters/omsendertrack-cmdfile.rst
|
||||
:start-after: .. summary-start
|
||||
:end-before: .. summary-end
|
||||
|
||||
.. csv-table::
|
||||
:header: "Type", "Default", "Mandatory", "|FmtObsoleteName| directive"
|
||||
:widths: auto
|
||||
:class: parameter-table
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
"string", "RSYSLOG_FileFormat", "no", "none"
|
||||
|
||||
This parameter defines the **template used to determine the sender's unique
|
||||
identifier**. The value produced by this template will be used as the key for
|
||||
tracking individual senders within the module's internal statistics.
|
||||
|
||||
For instance:
|
||||
|
||||
* A simple template like ``"%hostname%"`` will track each unique host that
|
||||
submits messages to rsyslog.
|
||||
* Using ``"%fromhost-ip%"`` will track senders based on their IP address.
|
||||
* A more granular template such as ``"%hostname%-%app-name%"`` can
|
||||
differentiate between applications on the same host.
|
||||
|
||||
**Note:** The processing of this template for every incoming message can impact
|
||||
overall throughput, especially if complex templates are used. Choose your
|
||||
template wisely based on your tracking needs and performance considerations.
|
||||
|
||||
interval
|
||||
^^^^^^^^
|
||||
|
||||
.. _omsendertrack_interval:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Type", "Default", "Mandatory", "|FmtObsoleteName| directive"
|
||||
:widths: auto
|
||||
:class: parameter-table
|
||||
|
||||
"integer", "60", "no", "none"
|
||||
|
||||
This parameter defines the **interval in seconds** after which the module
|
||||
writes the current sender statistics to the configured :ref:`statefile
|
||||
<omsendertrack_statefile>`.
|
||||
|
||||
A smaller `interval` value results in more frequent updates to the state file,
|
||||
reducing potential data loss in case of an unexpected system crash, but it also
|
||||
increases disk I/O. A larger `interval` reduces I/O but means less up-to-date
|
||||
statistics on disk.
|
||||
|
||||
statefile
|
||||
^^^^^^^^^
|
||||
|
||||
.. _omsendertrack_statefile:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Type", "Default", "Mandatory", "|FmtObsoleteName| directive"
|
||||
:widths: auto
|
||||
:class: parameter-table
|
||||
|
||||
"string", "none", "yes", "none"
|
||||
|
||||
This mandatory parameter specifies the **absolute path to the JSON file** where
|
||||
sender information will be stored. The module updates this file periodically
|
||||
based on the :ref:`interval <omsendertrack_interval>` and also upon rsyslog
|
||||
shutdown to preserve the latest statistics.
|
||||
|
||||
**Important:** Ensure that the rsyslog user has appropriate write permissions
|
||||
to the directory where this `statefile` is located. Failure to do so will
|
||||
prevent the module from saving its state.
|
||||
|
||||
cmdfile
|
||||
^^^^^^^
|
||||
|
||||
.. _omsendertrack_cmdfile:
|
||||
|
||||
.. csv-table::
|
||||
:header: "Type", "Default", "Mandatory", "|FmtObsoleteName| directive"
|
||||
:widths: auto
|
||||
:class: parameter-table
|
||||
|
||||
"string", "none", "no", "none"
|
||||
|
||||
This optional parameter allows you to specify the **absolute path to a command
|
||||
file**. This file *is designed to be processed when rsyslog receives a HUP
|
||||
signal* (e.g., via `systemctl reload rsyslog`).
|
||||
|
||||
**Note:** Command file support is currently **not implemented** in this
|
||||
proof-of-concept version of the module. When implemented, this feature is
|
||||
intended to allow dynamic control over the module's behavior, such as resetting
|
||||
statistics for specific senders, without requiring an rsyslog restart.
|
||||
../../reference/parameters/omsendertrack-senderid
|
||||
../../reference/parameters/omsendertrack-interval
|
||||
../../reference/parameters/omsendertrack-statefile
|
||||
../../reference/parameters/omsendertrack-cmdfile
|
||||
|
||||
Statistic Counter
|
||||
-----------------
|
||||
@ -208,7 +148,7 @@ Statistic Counter
|
||||
The ``omsendertrack`` module is designed to maintain a set of statistics for
|
||||
each unique sender identifier it tracks. These statistics are intended to be
|
||||
periodically serialized and written to the configured :ref:`statefile
|
||||
<omsendertrack_statefile>` in JSON format.
|
||||
<param-omsendertrack-statefile>` in JSON format.
|
||||
|
||||
**Important:** This module **does not offer statistics counters in the typical
|
||||
sense** that are consumable by other rsyslog modules like `impstats`. The
|
||||
@ -232,7 +172,7 @@ The JSON structure for each sender entry is envisioned to look like this:
|
||||
Where:
|
||||
|
||||
* ``senderid``: The unique identifier for the sender, as determined by the
|
||||
:ref:`senderid <omsendertrack_senderid>` template.
|
||||
:ref:`senderid <param-omsendertrack-senderid>` template.
|
||||
* ``last-event-time``: A UTC timestamp (ISO 8601 format) indicating when the
|
||||
last message from this sender was received.
|
||||
* ``message-count``: The total number of messages received from this sender
|
||||
@ -277,14 +217,17 @@ adhere to the following best practices:
|
||||
house the ``omsendertrack`` action (as shown in Example 2), ensure that
|
||||
this specific ruleset **does not have a queue configured**. The module's
|
||||
fast execution makes queues redundant here.
|
||||
* **Efficient Sender Identification:** Choose your :ref:`senderid <omsendertrack_senderid>` template carefully. Simpler templates (e.g., ``"%hostname%"``, ``"%fromhost-ip%"``) result in better performance, as template processing occurs for every message.
|
||||
* **Efficient Sender Identification:** Choose your
|
||||
:ref:`senderid <param-omsendertrack-senderid>` template carefully. Simpler
|
||||
templates (e.g., ``"%hostname%"``, ``"%fromhost-ip%"``) result in better
|
||||
performance, as template processing occurs for every message.
|
||||
* **Appropriate `interval` for State File Writes:** Balance your need for
|
||||
up-to-date statistics against disk I/O. A very small `interval` can lead
|
||||
to increased disk writes, while a larger one might mean slightly older data
|
||||
on disk in case of an unexpected shutdown.
|
||||
* **Ensure State File Write Permissions:** Verify that the rsyslog user has
|
||||
proper write permissions to the directory specified in the :ref:`statefile
|
||||
<omsendertrack_statefile>` parameter. Without this, statistics cannot be
|
||||
<param-omsendertrack-statefile>` parameter. Without this, statistics cannot be
|
||||
persisted.
|
||||
* **Dedicated Ruleset for Unified Stats:** Use a dedicated ruleset that is
|
||||
called from multiple input-bound rulesets (Example 2) **only when** you
|
||||
@ -314,9 +257,9 @@ when the overall volume is low.
|
||||
|
||||
module(load="omsendertrack")
|
||||
action(type="omsendertrack"
|
||||
senderid="%hostname%"
|
||||
senderId="%hostname%"
|
||||
interval="60"
|
||||
statefile="/var/lib/rsyslog/senderstats.json")
|
||||
stateFile="/var/lib/rsyslog/senderstats.json")
|
||||
|
||||
Example 2: Usage with Dedicated Ruleset
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -333,7 +276,7 @@ processing flows for other actions.
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
# Define the template for senderid in omsendertrack
|
||||
# Define the template for senderId in omsendertrack
|
||||
template(name="id-template" type="list") {
|
||||
property(name="hostname")
|
||||
}
|
||||
@ -343,10 +286,10 @@ processing flows for other actions.
|
||||
ruleset(name="omsendertrack-ruleset") {
|
||||
action(
|
||||
type="omsendertrack"
|
||||
senderid="id-template"
|
||||
senderId="id-template"
|
||||
interval="60"
|
||||
statefile="/var/lib/rsyslog/senderstats.json"
|
||||
cmdfile="/var/lib/rsyslog/sendercommands.txt"
|
||||
stateFile="/var/lib/rsyslog/senderstats.json"
|
||||
cmdFile="/var/lib/rsyslog/sendercommands.txt"
|
||||
)
|
||||
}
|
||||
|
||||
@ -426,9 +369,9 @@ state files.
|
||||
ruleset(name="udp-sender-tracking") {
|
||||
action(
|
||||
type="omsendertrack"
|
||||
senderid="%fromhost-ip%"
|
||||
senderId="%fromhost-ip%"
|
||||
interval="300"
|
||||
statefile="/var/lib/rsyslog/udp_sender_stats.json"
|
||||
stateFile="/var/lib/rsyslog/udp_sender_stats.json"
|
||||
)
|
||||
# Add other actions for UDP messages here (e.g., forwarding, writing to file)
|
||||
}
|
||||
@ -437,9 +380,9 @@ state files.
|
||||
ruleset(name="tcp-sender-tracking") {
|
||||
action(
|
||||
type="omsendertrack"
|
||||
senderid="%fromhost-ip%"
|
||||
senderId="%fromhost-ip%"
|
||||
interval="300"
|
||||
statefile="/var/lib/rsyslog/tcp_sender_stats.json"
|
||||
stateFile="/var/lib/rsyslog/tcp_sender_stats.json"
|
||||
)
|
||||
# Add other actions for TCP messages here
|
||||
}
|
||||
|
||||
53
doc/source/reference/parameters/omsendertrack-cmdfile.rst
Normal file
53
doc/source/reference/parameters/omsendertrack-cmdfile.rst
Normal file
@ -0,0 +1,53 @@
|
||||
.. _param-omsendertrack-cmdfile:
|
||||
.. _omsendertrack.parameter.input.cmdfile:
|
||||
|
||||
cmdfile
|
||||
=======
|
||||
|
||||
.. index::
|
||||
single: omsendertrack; cmdfile
|
||||
single: cmdfile
|
||||
|
||||
.. summary-start
|
||||
|
||||
Defines the absolute path to the command file that omsendertrack reads when
|
||||
rsyslog receives a HUP signal.
|
||||
|
||||
.. summary-end
|
||||
|
||||
This parameter applies to :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
:Name: cmdfile
|
||||
:Scope: input
|
||||
:Type: string
|
||||
:Default: input=none
|
||||
:Required?: no
|
||||
:Introduced: 8.2506.0 (Proof-of-Concept)
|
||||
|
||||
Description
|
||||
-----------
|
||||
This optional parameter allows you to specify the **absolute path to a command
|
||||
file**. This file *is designed to be processed when rsyslog receives a HUP
|
||||
signal* (for example via ``systemctl reload rsyslog``).
|
||||
|
||||
**Note:** Command file support is currently **not implemented** in this
|
||||
proof-of-concept version of the module. When implemented, this feature is
|
||||
intended to allow dynamic control over the module's behavior, such as resetting
|
||||
statistics for specific senders, without requiring an rsyslog restart.
|
||||
|
||||
Input usage
|
||||
-----------
|
||||
.. _omsendertrack.parameter.input.cmdfile-usage:
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
module(load="omsendertrack")
|
||||
action(type="omsendertrack"
|
||||
senderId="%hostname%"
|
||||
stateFile="/var/lib/rsyslog/senderstats.json"
|
||||
cmdFile="/var/lib/rsyslog/sendercommands.txt")
|
||||
|
||||
See also
|
||||
--------
|
||||
See also :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
53
doc/source/reference/parameters/omsendertrack-interval.rst
Normal file
53
doc/source/reference/parameters/omsendertrack-interval.rst
Normal file
@ -0,0 +1,53 @@
|
||||
.. _param-omsendertrack-interval:
|
||||
.. _omsendertrack.parameter.input.interval:
|
||||
|
||||
interval
|
||||
========
|
||||
|
||||
.. index::
|
||||
single: omsendertrack; interval
|
||||
single: interval
|
||||
|
||||
.. summary-start
|
||||
|
||||
Sets how many seconds elapse between each write of sender statistics to the
|
||||
state file.
|
||||
|
||||
.. summary-end
|
||||
|
||||
This parameter applies to :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
:Name: interval
|
||||
:Scope: input
|
||||
:Type: integer
|
||||
:Default: input=60
|
||||
:Required?: no
|
||||
:Introduced: 8.2506.0 (Proof-of-Concept)
|
||||
|
||||
Description
|
||||
-----------
|
||||
This parameter defines the **interval in seconds** after which the module
|
||||
writes the current sender statistics to the configured :ref:`statefile
|
||||
<param-omsendertrack-statefile>`.
|
||||
|
||||
A smaller ``interval`` value results in more frequent updates to the state
|
||||
file, reducing potential data loss in case of an unexpected system crash, but
|
||||
it also increases disk I/O. A larger ``interval`` reduces I/O but means less
|
||||
up-to-date statistics on disk.
|
||||
|
||||
Input usage
|
||||
-----------
|
||||
.. _omsendertrack.parameter.input.interval-usage:
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
module(load="omsendertrack")
|
||||
action(type="omsendertrack"
|
||||
senderId="%hostname%"
|
||||
interval="60"
|
||||
stateFile="/var/lib/rsyslog/senderstats.json")
|
||||
|
||||
See also
|
||||
--------
|
||||
See also :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
59
doc/source/reference/parameters/omsendertrack-senderid.rst
Normal file
59
doc/source/reference/parameters/omsendertrack-senderid.rst
Normal file
@ -0,0 +1,59 @@
|
||||
.. _param-omsendertrack-senderid:
|
||||
.. _omsendertrack.parameter.input.senderid:
|
||||
|
||||
senderid
|
||||
========
|
||||
|
||||
.. index::
|
||||
single: omsendertrack; senderid
|
||||
single: senderid
|
||||
|
||||
.. summary-start
|
||||
|
||||
Sets the template used to derive the unique sender identifier that
|
||||
omsendertrack tracks.
|
||||
|
||||
.. summary-end
|
||||
|
||||
This parameter applies to :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
:Name: senderid
|
||||
:Scope: input
|
||||
:Type: string
|
||||
:Default: input=RSYSLOG_FileFormat
|
||||
:Required?: no
|
||||
:Introduced: 8.2506.0 (Proof-of-Concept)
|
||||
|
||||
Description
|
||||
-----------
|
||||
This parameter defines the **template used to determine the sender's unique
|
||||
identifier**. The value produced by this template becomes the key for tracking
|
||||
individual senders within the module's internal statistics.
|
||||
|
||||
For instance:
|
||||
|
||||
* A simple template like ``"%hostname%"`` tracks each unique host that submits
|
||||
messages to rsyslog.
|
||||
* Using ``"%fromhost-ip%"`` tracks senders based on their IP address.
|
||||
* A more granular template such as ``"%hostname%-%app-name%"`` differentiates
|
||||
between applications on the same host.
|
||||
|
||||
**Note:** The processing of this template for every incoming message can impact
|
||||
overall throughput, especially if complex templates are used. Choose your
|
||||
template wisely based on your tracking needs and performance considerations.
|
||||
|
||||
Input usage
|
||||
-----------
|
||||
.. _omsendertrack.parameter.input.senderid-usage:
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
module(load="omsendertrack")
|
||||
action(type="omsendertrack"
|
||||
senderId="%hostname%"
|
||||
stateFile="/var/lib/rsyslog/senderstats.json")
|
||||
|
||||
See also
|
||||
--------
|
||||
See also :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
52
doc/source/reference/parameters/omsendertrack-statefile.rst
Normal file
52
doc/source/reference/parameters/omsendertrack-statefile.rst
Normal file
@ -0,0 +1,52 @@
|
||||
.. _param-omsendertrack-statefile:
|
||||
.. _omsendertrack.parameter.input.statefile:
|
||||
|
||||
statefile
|
||||
=========
|
||||
|
||||
.. index::
|
||||
single: omsendertrack; statefile
|
||||
single: statefile
|
||||
|
||||
.. summary-start
|
||||
|
||||
Specifies the absolute path to the JSON file where omsendertrack persists
|
||||
sender statistics.
|
||||
|
||||
.. summary-end
|
||||
|
||||
This parameter applies to :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
:Name: statefile
|
||||
:Scope: input
|
||||
:Type: string
|
||||
:Default: input=none
|
||||
:Required?: yes
|
||||
:Introduced: 8.2506.0 (Proof-of-Concept)
|
||||
|
||||
Description
|
||||
-----------
|
||||
This mandatory parameter specifies the **absolute path to the JSON file** where
|
||||
sender information is stored. The module updates this file periodically based
|
||||
on the configured :ref:`interval <param-omsendertrack-interval>` and also upon
|
||||
rsyslog shutdown to preserve the latest statistics.
|
||||
|
||||
**Important:** Ensure that the rsyslog user has appropriate write permissions to
|
||||
the directory where this ``statefile`` is located. Failure to do so will
|
||||
prevent the module from saving its state.
|
||||
|
||||
Input usage
|
||||
-----------
|
||||
.. _omsendertrack.parameter.input.statefile-usage:
|
||||
|
||||
.. code-block:: rsyslog
|
||||
|
||||
module(load="omsendertrack")
|
||||
action(type="omsendertrack"
|
||||
senderId="%hostname%"
|
||||
stateFile="/var/lib/rsyslog/senderstats.json")
|
||||
|
||||
See also
|
||||
--------
|
||||
See also :doc:`../../configuration/modules/omsendertrack`.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user