userguide: document exception policy stats

Configuration options and defaults, existing counters etc.

Related to
Task #5816

doc/userguide/configuration/exception-policies.rst

@@ -7,7 +7,10 @@ Suricata has a set of configuration variables to indicate what should the engine
 do when certain exception conditions, such as hitting a memcap, are reached.
 
 They are called Exception Policies and are configurable via suricata.yaml. If
-enabled, the engine will call them when it reaches exception states.
+enabled, the engine will call them when it reaches exception states. Stats for
+any applied exception policies can be found in counters related to the specific
+configuration setting (:ref:`read more<eps_stats>`). Some configuration is
+available directly via the :ref:`stats settings<suricata_yaml_outputs>`.
 
 For developers or for researching purposes, there are also simulation options
 exposed in debug mode and passed via command-line. These exist to force or
@@ -207,6 +210,43 @@ Notes:
    * Not valid means that Suricata will error out and won't start.
    * ``REJECT`` will make Suricata send a Reset-packet unreach error to the sender of the matching packet.
 
+.. _eps_stats:
+
+Available Stats
+---------------
+
+There are stats counters for each supported exception policy scenario:
+
+.. list-table:: **Exception Policy Stats Counters**
+   :widths: 50 50
+   :header-rows: 1
+   :stub-columns: 1
+
+   * - Setting
+     - Counter
+   * - stream.memcap
+     - tcp.ssn_memcap_exception_policy
+   * - stream.reassembly.memcap
+     - tcp.reassembly_memcap_exception_policy
+   * - stream.midstream
+     - tcp.midstream_exception_policy
+   * - defrag.memcap
+     - defrag.memcap_exception_policy
+   * - flow.memcap
+     - flow.memcap_exception_policy
+   * - app-layer.error
+     - app_layer.error.exception_policy
+
+If a given exception policy does not apply for a setting, no related counter
+is logged.
+
+Stats for application layer errors are available in summarized form or per
+application layer protocol. As the latter is extremely verbose, by default
+Suricata logs only the summary. If any further investigation is needed, it
+is recommended to enable per-app-proto exception policy error counters
+temporarily (for :ref:`stats configuration<suricata_yaml_outputs>`).
+
+
 Command-line Options for Simulating Exceptions
 ----------------------------------------------
 

doc/userguide/configuration/suricata-yaml.rst

@@ -317,6 +317,11 @@ the global config is documented.
       #decoder-events-prefix: "decoder.event"
       # Add stream events as stats.
       #stream-events: false
+      # Exception policy stats counters options
+      # (Note: if exception policy: ignore, counters are not logged)
+      exception-policy:
+        #per-app-proto-errors: false  # default: false. True will log errors for
+                                        # each app-proto. Warning: VERY verbose
 
 Statistics can be `enabled` or disabled here.
 
@@ -339,6 +344,10 @@ Similar to the `decoder-events` option, the `stream-events` option controls
 whether the stream-events are added as counters as well. This is disabled by
 default.
 
+If any exception policy is enabled, stats counters are logged. To control
+verbosity for application layer protocol errors, leave `per-app-proto-errors`
+as false.
+
 Outputs
 ~~~~~~~