userguide: expand documentation for rule profiling

The page about performance and rule profiling showed the table generated
by rules profiling but didn't inform how to achieve nor find it.

Task #4359

diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
index ffc540585f1119a11710e5eb371bb9e4cd0f0d33..6908c804ed0ae99f2723415120c7a4b72840b081 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -2631,6 +2631,9 @@ Example:
   Original content: abc
   Final content: bc
 
+
+.. _rule-and-packet-profiling-settings:
+
 Rule and Packet Profiling settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/doc/userguide/performance/rule-profiling.rst b/doc/userguide/performance/rule-profiling.rst
index f05e8fb4e482795aa3d4f99c62957558506a007a..6a600a1cce023403cf5b4d4516b97814d22ffefb 100644 (file)
--- a/doc/userguide/performance/rule-profiling.rst
+++ b/doc/userguide/performance/rule-profiling.rst
@@ -1,7 +1,20 @@
 Rule Profiling
 ==============
 
-::
+Suricata can generate a rules performance report at the end of each session, if
+built with the ``enable-profiling`` option (see configuring :ref:`Rule profiling
+<rule-and-packet-profiling-settings>`). With that option, the engine will also
+generate profiling data for other engine modules, such as packet processing.
+
+Rule profiling can also be enabled by building the engine with ``enable-profiling
+-rules`` and using the unix socket to dump the report (see
+:ref:`rule-management-rules-profiling`). This will enable profiling of rules'
+statistics only.
+
+Once the report is generated, it is stored in the default log directory used by
+Suricata. If not changed, the filename will be ``rule_perf.log``.
+
+A Rules Profile report looks like this: ::
 
   --------------------------------------------------------------------------
   Date: 9/5/2013 -- 14:59:58
@@ -21,13 +34,13 @@ Rule Profiling
 
 The meaning of the individual fields:
 
-* Ticks -- total ticks spent on this rule, so a sum of all inspections
-* % -- share of this single sig in the total cost of inspection
-* Checks -- number of times a signature was inspected
+* Ticks -- total ticks spent on this rule, so a sum of all inspections.
+* % -- share of this single signature in the total cost of inspection.
+* Checks -- number of times a signature was inspected.
 * Matches -- number of times it matched. This may not have resulted in an alert due to suppression and thresholding.
-* Max ticks -- single most expensive inspection
+* Max ticks -- single most expensive inspection.
 * Avg ticks -- per inspection average, so "ticks" / "checks".
-* Avg match -- avg ticks spent resulting in match
+* Avg match -- avg ticks spent resulting in match.
 * Avg No Match -- avg ticks spent resulting in no match.
 
 The "ticks" are CPU clock ticks: http://en.wikipedia.org/wiki/CPU_time

diff --git a/doc/userguide/rule-management/rule-profiling.rst b/doc/userguide/rule-management/rule-profiling.rst
index 2c9926005c299696c62281cbd14462fbd006b83e..e751779936b00716760dd1b5c5119bee445a54e0 100644 (file)
--- a/doc/userguide/rule-management/rule-profiling.rst
+++ b/doc/userguide/rule-management/rule-profiling.rst
@@ -1,3 +1,5 @@
+.. _rule-management-rules-profiling:
+
 Rules Profiling
 ===============