From cd05a404cdb7290631f23bb3bc827b84f38cf28a Mon Sep 17 00:00:00 2001
From: Stephan Bosch <stephan@rename-it.nl>
Date: Thu, 7 Apr 2016 04:31:30 +0200
Subject: [PATCH] Documented new trace debugging features.

---
 INSTALL                                 | 39 +++++++++++++++++++++++++
 doc/example-config/conf.d/90-sieve.conf | 34 +++++++++++++++++++++
 2 files changed, 73 insertions(+)

diff --git a/INSTALL b/INSTALL
index d0edabe9f..8be860b67 100644
--- a/INSTALL
+++ b/INSTALL
@@ -519,6 +519,45 @@ Sieve Interpreter - Extension Configuration
 
   Refer to doc/plugins/imapsieve.txt for more information.
 
+Sieve Interpreter - Trace Debugging
+-----------------------------------
+
+Trace debugging provides detailed insight in the operations performed by
+the Sieve script. Messages about what the Sieve script is doing are written
+to the specified directory.
+
+WARNING: On a busy server, this functionality can quickly fill up the trace
+directory with a lot of trace files. Enable this only temporarily and as
+selective as possible.
+
+The following settings apply to both the LDA Sieve plugin and the IMAPSIEVE
+plugin:
+
+ sieve_trace_dir =  
+  The directory where trace files are written. Trace debugging is disabled if
+  this setting is not configured or if the directory does not exist. If the 
+  path is relative or it starts with "~/" it is interpreted relative to the
+  current user's home directory.
+
+ sieve_trace_level = 
+   The verbosity level of the trace messages. Trace debugging is disabled if
+   this setting is not configured. Possible values are:
+  
+     "actions"  - Only print executed action commands, like keep, fileinto,
+                  reject and redirect.
+     "commands" - Print any executed command, excluding test commands.
+     "tests"    - Print all executed commands and performed tests.
+     "matching" - Print all executed commands, performed tests and the values
+                  matched in those tests.
+
+ sieve_trace_debug = no  
+   Enables highly verbose debugging messages that are usually only useful for
+   developers.
+
+ sieve_trace_addresses = no   
+   Enables showing byte code addresses in the trace output, rather than only
+   the source line numbers.
+
 Sieve Interpreter - Migration from CMUSieve (Dovecot v1.0/v1.1)
 ---------------------------------------------------------------
 
diff --git a/doc/example-config/conf.d/90-sieve.conf b/doc/example-config/conf.d/90-sieve.conf
index ffabe13b0..f516ba42d 100644
--- a/doc/example-config/conf.d/90-sieve.conf
+++ b/doc/example-config/conf.d/90-sieve.conf
@@ -156,4 +156,38 @@ plugin {
   # This setting is ignored when the envelope sender is "<>". In that case the
   # sender of the redirected message is also always "<>".
   #sieve_redirect_envelope_from = sender
+
+  ## TRACE DEBUGGING
+  # Trace debugging provides detailed insight in the operations performed by
+  # the Sieve script. These settings apply to both the LDA Sieve plugin and the
+  # IMAPSIEVE plugin. 
+  #
+  # WARNING: On a busy server, this functionality can quickly fill up the trace
+  # directory with a lot of trace files. Enable this only temporarily and as
+  # selective as possible.
+  
+  # The directory where trace files are written. Trace debugging is disabled if
+  # this setting is not configured or if the directory does not exist. If the 
+  # path is relative or it starts with "~/" it is interpreted relative to the
+  # current user's home directory.
+  #sieve_trace_dir =
+  
+  # The verbosity level of the trace messages. Trace debugging is disabled if
+  # this setting is not configured. Possible values are:
+  #
+  #   "actions"        - Only print executed action commands, like keep,
+  #                      fileinto, reject and redirect.
+  #   "commands"       - Print any executed command, excluding test commands.
+  #   "tests"          - Print all executed commands and performed tests.
+  #   "matching"       - Print all executed commands, performed tests and the
+  #                      values matched in those tests.
+  #sieve_trace_level =
+  
+  # Enables highly verbose debugging messages that are usually only useful for
+  # developers.
+  #sieve_trace_debug = no
+  
+  # Enables showing byte code addresses in the trace output, rather than only
+  # the source line numbers.
+  #sieve_trace_addresses = no 
 }