[trafficserver] 01/02: Adding max line length configuration documentation.

[zw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

zwoop pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/trafficserver.git

commit a886e93e9e765190521f4e9ebdedd173dffd6ea3
Author: bneradt <bn...@verizonmedia.com>
AuthorDate: Mon Jan 6 22:54:52 2020 +0000

    Adding max line length configuration documentation.
    
    (cherry picked from commit 52a779c5051d6b7d5de549d6b1b24216df84a8d7)
---
 doc/admin-guide/logging/formatting.en.rst | 32 +++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/doc/admin-guide/logging/formatting.en.rst b/doc/admin-guide/logging/formatting.en.rst
index 182199c..9f095ab 100644
--- a/doc/admin-guide/logging/formatting.en.rst
+++ b/doc/admin-guide/logging/formatting.en.rst
@@ -797,6 +797,38 @@ cquup Client Request Canonical (prior to remapping) path component from the
 cquuh Client Request Unmapped URL host from the client request.
 ===== ============== ==========================================================
 
+Line Length
+===========
+
+The maximum line size for a log entry can be configured via the following parameters:
+
+- :ts:cv:`proxy.config.log.max_line_size`: This controls the maximum line
+  length for ASCII formatted log entries. This applies to ``ASCII_PIPE`` and
+  ``ASCII`` file logs, *unless* :ts:cv:`proxy.config.log.ascii_buffer_size` is
+  also specified and the value of :ts:cv:`ascii_buffer_size` is larger than
+  :ts:cv:`max_line_size`: in that case, :ts:cv:`max_line_size` only applies to
+  ``ASCII_PIPE`` logs while :ts:cv:`ascii_buffer_size` will apply to ``ASCII``
+  (non-pipe) log files.
+
+- :ts:cv:`proxy.config.log.ascii_buffer_size`: This controls the maximum line
+  length for ASCII formatted log entries that are non-pipe log files. If this
+  value is smaller than :ts:cv:`proxy.config.log.max_line_size`, then the
+  latter will be used for both ``ASCII`` and ``ASCII_PIPE`` log files. If both
+  :ts:cv:`max_line_size` and :ts:cv:`ascii_buffer_size` are set, then
+  :ts:cv:`max_line_size` will be used for ``ASCII_PIPE`` logs while
+  :ts:cv:`ascii_buffer_size` will be used for ``ASCII`` (non-pipe) log files.
+  This all might seem complicated, but just keep in mind that the intention of
+  :ts:cv:`ascii_buffer_size` is to simply provide a way for the user to
+  configure different ``ASCII`` and ``ASCII_PIPE`` maximum line lengths.
+
+- :ts:cv:`proxy.config.log.log_buffer_size`: This is an orthogonal mechanism
+  for limiting line length size by constraining the log entry buffer to a
+  particular amount of memory. Unlike the above two configurations,
+  :ts:cv:`log_buffer_size` applies to both binary and ASCII log file entries.
+  For ASCII log files, if a maximum log size is set via the above mechanisms
+  and by :ts:cv:`log_buffer_size`, then the smaller of the two configurations
+  will be applied to the line length.
+
 Log Field Slicing
 =================