From: Jeff Lucovsky <jeff@lucovsky.org>
Date: Thu, 30 Jul 2020 11:08:12 +0000 (-0400)
Subject: doc/output: Document multithreaded eve option
X-Git-Tag: suricata-6.0.0-beta1~62
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a5d30a32201693aca74eae80b40424e58bd6d6f8;p=thirdparty%2Fsuricata.git

doc/output: Document multithreaded eve option
---

diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
index badc14874d..a8c7ce9320 100644
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -24,6 +24,9 @@ Output types::
 
       filetype: regular #regular|syslog|unix_dgram|unix_stream|redis
       filename: eve.json
+      # Enable for multi-threaded eve.json output; output files are suffixed
+      # with an identifier, e.g., eve.json.9.. Default: off
+      #threaded: off
       #prefix: "@cee: " # prefix to prepend to each log entry
       # the following are valid when type: syslog above
       #identity: "suricata"
@@ -298,6 +301,25 @@ modifiers.
 
 .. _output_eve_rotate:
 
+Threaded file output
+~~~~~~~~~~~~~~~~~~~~
+
+By default, all output is written to the named filename in the outputs section. The ``threaded`` option enables
+each output thread to write to individual files prefixed with the configured ``filenmae``.
+
+::
+
+   outputs:
+     - eve-log:
+         filename: eve.json
+         threaded: on
+
+This example will cause each Suricata thread to write to its own "eve.json" file. Filenames are constructed
+by adding a suffix with the thread id. For example, the thread with id 7 would write to `eve.json.7`.
+
+With ``threaded`` enabled, the output will be split among many files -- each having the same prefix and a unique suffix -- and
+the aggregate of each file's contents must be treated together.
+
 Rotate log file
 ~~~~~~~~~~~~~~~
 
diff --git a/doc/userguide/partials/eve-log.yaml b/doc/userguide/partials/eve-log.yaml
index f4b3c7e15a..d90e409eaf 100644
--- a/doc/userguide/partials/eve-log.yaml
+++ b/doc/userguide/partials/eve-log.yaml
@@ -4,6 +4,9 @@ outputs:
       enabled: yes
       filetype: regular #regular|syslog|unix_dgram|unix_stream|redis
       filename: eve.json
+      # Enable for multi-threaded eve.json output; output files are suffixed
+      # with an identifier, e.g., eve.json.9.
+      #threaded: false
       #prefix: "@cee: " # prefix to prepend to each log entry
       # the following are valid when type: syslog above
       #identity: "suricata"