From 0c9b545ea7127b041ecaba151dc6bd085bbd1a8b Mon Sep 17 00:00:00 2001
From: Tim Burke <tim.burke@gmail.com>
Date: Fri, 4 Aug 2023 11:30:42 -0700
Subject: [PATCH] docs: Clean up proxy logging docs

Change-Id: I6ef909e826d3901f24d3c42a78d2ab1e4e47bb64
---
 doc/source/logs.rst                      | 10 ++++++----
 etc/proxy-server.conf-sample             |  3 ++-
 swift/common/middleware/proxy_logging.py | 15 ++++++++++-----
 3 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/doc/source/logs.rst b/doc/source/logs.rst
index d7a64a802a..ade72e35c1 100644
--- a/doc/source/logs.rst
+++ b/doc/source/logs.rst
@@ -37,7 +37,7 @@ The default log format is::
 
 Some keywords, signaled by the (anonymizable) flag, can be anonymized by
 using the transformer 'anonymized'. The data are applied the hashing method of
-`log_anonymization_method` and an optional salt `log_anonymization_salt`.
+``log_anonymization_method`` and an optional salt ``log_anonymization_salt``.
 
 Some keywords, signaled by the (timestamp) flag, can be converted to standard
 dates formats using the matching transformers: 'datetime', 'asctime' or
@@ -46,9 +46,11 @@ seconds, milliseconds, microseconds and nanoseconds. Python's strftime
 directives can also be used as tranformers (a, A, b, B, c, d, H, I, j, m, M, p,
 S, U, w, W, x, X, y, Y, Z).
 
-Example {client_ip.anonymized} {remote_addr.anonymized} {start_time.iso8601}
-            {end_time.H}:{end_time.M} {method} acc:{account} cnt:{container}
-            obj:{object.anonymized}
+Example::
+
+    {client_ip.anonymized} {remote_addr.anonymized} {start_time.iso8601}
+        {end_time.H}:{end_time.M} {method} acc:{account} cnt:{container}
+        obj:{object.anonymized}
 
 =================== ==========================================================
 **Log Field**       **Value**
diff --git a/etc/proxy-server.conf-sample b/etc/proxy-server.conf-sample
index c47b0cdb24..a0a44d181f 100644
--- a/etc/proxy-server.conf-sample
+++ b/etc/proxy-server.conf-sample
@@ -1028,7 +1028,8 @@ use = egg:swift#proxy_logging
 # log_anonymization_salt =
 #
 # Template used to format access logs. All words surrounded by curly brackets
-# will be substituted with the appropriate values
+# will be substituted with the appropriate values. For more information, see
+# https://docs.openstack.org/swift/latest/logs.html
 # log_msg_template = {client_ip} {remote_addr} {end_time.datetime} {method} {path} {protocol} {status_int} {referer} {user_agent} {auth_token} {bytes_recvd} {bytes_sent} {client_etag} {transaction_id} {headers} {request_time} {source} {log_info} {start_time} {end_time} {policy_index}
 
 # Note: Put before both ratelimit and auth in the pipeline.
diff --git a/swift/common/middleware/proxy_logging.py b/swift/common/middleware/proxy_logging.py
index 3cf2aee623..aad949cdd9 100644
--- a/swift/common/middleware/proxy_logging.py
+++ b/swift/common/middleware/proxy_logging.py
@@ -19,12 +19,12 @@ Logging middleware for the Swift proxy.
 This serves as both the default logging implementation and an example of how
 to plug in your own logging format/method.
 
-The logging format implemented below is as follows:
+The logging format implemented below is as follows::
 
-client_ip remote_addr end_time.datetime method path protocol
-    status_int referer user_agent auth_token bytes_recvd bytes_sent
-    client_etag transaction_id headers request_time source log_info
-    start_time end_time policy_index
+    client_ip remote_addr end_time.datetime method path protocol
+        status_int referer user_agent auth_token bytes_recvd bytes_sent
+        client_etag transaction_id headers request_time source log_info
+        start_time end_time policy_index
 
 These values are space-separated, and each is url-encoded, so that they can
 be separated with a simple .split()
@@ -49,6 +49,11 @@ be separated with a simple .split()
 * Values that are missing (e.g. due to a header not being present) or zero
   are generally represented by a single hyphen ('-').
 
+.. note::
+   The message format may be configured using the ``log_msg_template`` option,
+   allowing fields to be added, removed, re-ordered, and even anonymized. For
+   more information, see https://docs.openstack.org/swift/latest/logs.html
+
 The proxy-logging can be used twice in the proxy server's pipeline when there
 is middleware installed that can return custom responses that don't follow the
 standard pipeline to the proxy server.