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

doc/source/configuration/modules/omsendertrack.rst

@@ -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::
+.. toctree::
-   :header: "Type", "Default", "Mandatory", "|FmtObsoleteName| directive"
+   :hidden:
-   :widths: auto
-   :class: parameter-table
 
-   "string", "RSYSLOG_FileFormat", "no", "none"
+   ../../reference/parameters/omsendertrack-senderid
-
+   ../../reference/parameters/omsendertrack-interval
-This parameter defines the **template used to determine the sender's unique
+   ../../reference/parameters/omsendertrack-statefile
-identifier**. The value produced by this template will be used as the key for
+   ../../reference/parameters/omsendertrack-cmdfile
-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.
 
 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"
+           stateFile="/var/lib/rsyslog/senderstats.json"
-           cmdfile="/var/lib/rsyslog/sendercommands.txt"
+           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
    }

doc/source/reference/parameters/omsendertrack-cmdfile.rst

@@ -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`.
+

doc/source/reference/parameters/omsendertrack-interval.rst

@@ -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`.
+

doc/source/reference/parameters/omsendertrack-senderid.rst

@@ -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`.
+

doc/source/reference/parameters/omsendertrack-statefile.rst

@@ -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`.
+