TASK-113041: New configuration options for debug throttling

content/momentum/3/3-push/push-http-request-eval.md

@@ -32,7 +32,7 @@ function mod:http_request_eval(sess)
     DzyjAI8maYIogujSPtq-jSUG0WybCQ0mT1eGOZsgy0"
   local request = "{ \"registration_ids\": [ \"" .. reg_id .. "\" ], \"dry_run\": true, »
     \"data\": { \"message\": \"Push message to send over GCM\" } }"
-  local auth_key = "AIzaSyA09R1jflwVV4T79OIuLtTxQyXKFlOVQfs"
+  local auth_key = "REDACTED"
 
   -- print new json request to paniclog.ec for ref
   print ("new json request = ", request)
@@ -69,4 +69,4 @@ You must use require `("msys.httpclnt")` to enable this hook point and to access
 
 After changing HTTP session data, be sure to use the `sess:request_finalize` function.
 
-The [ob_get_current_message](/momentum/3/3-reference/3-reference-lua-ref-msys-delivery-ob-get-current-message) function uses this parameter to return a message. See also [Lua Functions](/momentum/3/3-reference/3-reference-lua-summary-table) for more information about the functions used in [“http_response_eval example”](/momentum/3/3-push/push-http-response-eval#push.http_response_eval.example).
+The [ob_get_current_message](/momentum/3/3-reference/3-reference-lua-ref-msys-delivery-ob-get-current-message) function uses this parameter to return a message. See also [Lua Functions](/momentum/3/3-reference/3-reference-lua-summary-table) for more information about the functions used in [“http_response_eval example”](/momentum/3/3-push/push-http-response-eval#push.http_response_eval.example).

content/momentum/4/config-options-summary.md

@@ -111,6 +111,8 @@ The `Version` column indicated the version(s) of Momentum that support the optio
 | [debug](/momentum/4/config/ref-debug-flags) – Set the debug level | na |   | 4.0 and later | debug_flags |
 | [debug_flags](/momentum/4/config/ref-debug-flags) *(scope)* – Configure debug verbosity | na |   | 4.0 and later | global |
 | [debug_level](/momentum/4/4-module-config) – Set the module debug level (applicable to all modules) (cluster-specific) | na | error | 4.0 and later | cluster |
+| [debug_throttle_max_num_same_message](/momentum/4/config/ref-debug-throttle) – Maximum number of identical debug messages to log within an interval | na | 0 | 5.2 and later | global |
+| [debug_throttle_period_secs](/momentum/4/config/ref-debug-throttle) – Time interval for debug message throttling, in seconds | na | 1 | 5.2 and later | global |
 | [default_binding](/momentum/4/config/ref-default-binding) – Control the default binding | sending | normal | 4.0 and later | global |
 | [default_charset](/momentum/4/config/ref-default-charset) – Control the character set | both | us-ascii | 4.0 and later | global, pathway, pathway_group |
 | [delay_dsn_max_retry_interval](/momentum/4/config/ref-delay-dsn-max-retry-interval) – Maximum interval for sending DSNs to the sender of a message that has not yet been delivered | sending | 43200 | 4.0 and later | binding, binding_group, domain, global |

content/momentum/4/config/ref-debug-throttle.md

@@ -0,0 +1,89 @@
+---
+lastUpdated: "12/31/2025"
+title: "Throttling Debug Messages"
+description: "Configure throttling to tell Momentum how to suppress repeated debug messages. When using the default logging module the messages will appear in the paniclog. The throttle is a decimal number representing the maximum number of repeated debug messages to log within a specified time interval"
+---
+
+When using the default logging module, debug messages will appear in the [paniclog](/momentum/4/log-formats-paniclog)
+depending on subsystem and level settings configured in [Debug_Flags](/momentum/4/config/ref-debug-flags). `Debug_Flags` is
+usually empty, so very few events are written to the `paniclog`. However, under certain circumstances, you need to get more
+information about some subsystem's behavior (e.g., SMTP), then by setting `Debug_Flags`, you can enable more verbose logging
+into `paniclog`. On the other hand, depending on the chosen level, `paniclog` may get populated with several lines of the same
+message, including some that might not be of your interest.
+
+Momentum’s debug throttling configuration allows you to suppress repeated debug messages. The throttle suppresses the logging
+of repeated messages beyond a specified limit during a time interval also specified. It is a global setting that applies to
+messages of all subsystems.
+
+> **NOTE:** Debug throttling global configuration **DOES NOT** apply to messages logged at the `CRITICAL`, `ERROR`, or
+> `WARNING` levels of any subsystem, due to their relevance for operation and diagnosis.
+
+It is important to note that debug throttling is applied not necessarily to *identical* messages, but to messages that are
+considered the same after removing variable parts such as timestamps, IP addresses, or other dynamic content. In other words,
+if the source of the message is something like this:
+
+```
+<timestamp> Message received from: <mailfrom>
+```
+
+then all messages that match this pattern will be considered the same for throttling purposes, regardless of the actual
+values of `<timestamp>` and `<mailfrom>`. This happens because the default logging module is based on `printf`-style
+formatting, which allows variable content in log messages, and it is the formatting that determines message sameness.
+
+<a name="conf.ref.debug_throttle"></a>
+# Configuration options
+
+Debug throttling is configured using the following options in the global scope of your `ecelerity.conf` file:
+- **debug_throttle_max_num_same_message**
+- **debug_throttle_period_secs**
+
+<a name="conf.ref.debug_throttle_max_num_same_message"></a> 
+## Maximum number of the same message
+
+<a name="conf.ref.debug_throttle_max_num_same_message.name"></a> 
+### Name
+
+`debug_throttle_max_num_same_message`
+
+<a name="conf.ref.debug_throttle_max_num_same_message.description"></a> 
+### Description
+
+Sets the maximum number of repeated debug messages to log within a specified time interval. The default is `0`, which means no
+throttling is applied to the logging of repeated debug messages.
+
+<a name="conf.ref.debug_throttle_period_secs.example"></a>
+### Example
+
+```
+debug_throttle_max_num_same_message = 5
+```
+
+With this configuration, only five lines of the same debug message will be logged during the time interval specified by
+`debug_throttle_period_secs`.
+
+<a name="conf.ref.debug_throttle_period_secs"></a> 
+## Time interval of throttling
+
+<a name="conf.ref.debug_throttle_period_secs.name"></a> 
+### Name
+`debug_throttle_period_secs`
+
+<a name="conf.ref.debug_throttle_period_secs.description"></a>
+### Description
+
+Sets the time interval in seconds during which repeated debug messages are counted for throttling purposes. The default is
+`1` second, with a maximum of `60` seconds.
+
+<a name="conf.ref.debug_throttle_period_secs.example"></a>
+### Example
+```
+debug_throttle_period_secs = 30
+```
+With this configuration, the time interval for counting repeated debug messages is set to 30 seconds. Combined with the
+previous example for `debug_throttle_max_num_same_message`, only five lines of the same debug message will be logged every
+30 seconds.
+
+<a name="conf.ref.debug_throttle.scope"></a> 
+# Scope
+
+Debug throttling options are valid in the global scope.